sys/man/2/exec

   1 .TH EXEC 2
   2 .SH NAME
   3 exec, execl, _privates, _nprivates, _tos \- execute a file
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .PP
   9 .nf
  10 .B
  11 int exec(char *name, char* argv[])
  12 .PP
  13 .B
  14 int execl(char *name, ...)
  15 .PP
  16 .B
  17 void    **_privates;
  18 .PP
  19 .B
  20 int     _nprivates;
  21 .PP
  22 .B
  23 #include <tos.h>
  24 .PP
  25 .ft L
  26 typedef struct Tos Tos;
  27 struct Tos {
  28     struct { ... } prof;    /* profiling data */
  29     uvlong  cyclefreq;      /* cycle clock frequency */
  30     vlong   kcycles;        /* kernel cycles */
  31     vlong   pcycles;        /* process cycles (kernel + user) */
  32     ulong   pid;            /* process id */
  33     ulong   clock;          /* profiling clock */
  34     /* top of stack is here */
  35 };
  36 .PP
  37 .B
  38 extern Tos *_tos;
  39 .fi
  40 .SH DESCRIPTION
  41 .I Exec
  42 and
  43 .I execl
  44 overlay the calling process with the named file, then
  45 transfer to the entry point of the image of the file.
  46 .PP
  47 .I Name
  48 points to the name of the file
  49 to be executed; it must not be a directory, and the permissions
  50 must allow the current user to execute it
  51 (see
  52 .IR stat (2)).
  53 It should also be a valid binary image, as defined in the
  54 .IR a.out (6)
  55 for the current machine architecture,
  56 or a shell script
  57 (see
  58 .IR rc (1)).
  59 The first line of a
  60 shell script must begin with
  61 .L #!
  62 followed by the name of the program to interpret the file
  63 and any initial arguments to that program, for example
  64 .IP
  65 .EX
  66 #!/bin/rc
  67 ls | mc
  68 .EE
  69 .PP
  70 When a C program is executed,
  71 it is called as follows:
  72 .IP
  73 .EX
  74 void main(int argc, char *argv[])
  75 .EE
  76 .PP
  77 .I Argv
  78 is a copy of the array of argument pointers passed to
  79 .IR exec ;
  80 that array must end in a null pointer, and
  81 .I argc
  82 is the number of elements before the null pointer.
  83 By convention, the first argument should be the name of
  84 the program to be executed.
  85 .I Execl
  86 is like
  87 .I exec
  88 except that
  89 .I argv
  90 will be an array of the parameters that follow
  91 .I name
  92 in the call.  The last argument to
  93 .I execl
  94 must be a null pointer.
  95 .PP
  96 For a file beginning
  97 .BR #! ,
  98 the arguments passed to the program
  99 .RB ( /bin/rc
 100 in the example above) will be the name of the file being
 101 executed, any arguments on the
 102 .B #!
 103 line, the name of the file again,
 104 and finally the second and subsequent arguments given to the original
 105 .I exec
 106 call.
 107 The result honors the two conventions of a program accepting as argument
 108 a file to be interpreted and
 109 .B argv[0]
 110 naming the file being
 111 executed.
 112 .PP
 113 Most attributes of the calling process are carried
 114 into the result; in particular,
 115 files remain open across
 116 .I exec
 117 (except those opened with
 118 .B OCEXEC
 119 OR'd
 120 into the open mode; see
 121 .IR open (2));
 122 and the working directory and environment
 123 (see
 124 .IR env (3))
 125 remain the same.
 126 However, a newly
 127 .I exec'ed
 128 process has no notification handler
 129 (see
 130 .IR notify (2)).
 131 .PP
 132 The global cell
 133 .B _privates
 134 points to an array of
 135 .B _nprivates
 136 elements of per-process private data.
 137 This storage is private for each process, even if the processes share data segments.
 138 .PP
 139 When the new program begins, the global pointer
 140 .B _tos
 141 is set to the address of a structure
 142 that holds information
 143 allowing accurate time keeping and clock reading in user space.
 144 These data are updated by the kernel during of the life of the process,
 145 including across
 146 .IR rfork s
 147 and
 148 .IR exec s.
 149 If there is a user-space accessible fast clock (a processor
 150 cycle counter),
 151 .B cyclefreq
 152 will be set to its frequency in Hz.
 153 .B Kcycles
 154 .RB ( pcycles )
 155 counts the number of cycles
 156 this process has spent in kernel mode
 157 (kernel and user mode).
 158 .B Pid
 159 is the current process's id.
 160 .B Clock
 161 is the user-profiling clock (see
 162 .IR prof (1)).
 163 Its time is measured in milliseconds but is updated at
 164 a system-dependent lower rate.
 165 This clock is typically used by the profiler but is available
 166 to all programs.
 167 .PP
 168 The above conventions apply to C programs; the raw system
 169 interface to the new image is as follows:
 170 the word pointed to by the stack pointer is
 171 .BR argc ;
 172 the words beyond that are the zeroth and subsequent elements
 173 of
 174 .BR argv ,
 175 followed by a terminating null pointer; and
 176 the return register (e.g.
 177 .B R0
 178 on the 68020) contains the address of the clock information.
 179 .SH SOURCE
 180 .B /sys/src/libc/9syscall
 181 .br
 182 .B /sys/src/libc/port/execl.c
 183 .SH SEE ALSO
 184 .IR prof (1),
 185 .IR intro (2),
 186 .IR stat (2)
 187 .SH DIAGNOSTICS
 188 If these functions fail, they return and set
 189 .IR errstr .
 190 There can be no return to the calling process from a successful
 191 .I exec
 192 or
 193 .IR execl ;
 194 the calling image is lost.
 195 .SH BUGS
 196 There is a large but finite limit on the size of an argment list,
 197 typically around 409,600 bytes.
 198 The kernel constant
 199 .B TSTKSIZ
 200 controls this.