1 .TH EXEC 3
2 .SH NAME
3 exec, execl, _clock, _privates, _nprivates \- 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 long	*_clock;
18 .PP
19 .B
20 void	**_privates;
21 .PP
22 .B
23 int	_nprivates;
24 .fi
25 .SH DESCRIPTION
26 .I Exec
27 and
28 .I execl
29 overlay the calling process with the named file, then
30 transfer to the entry point of the image of the file.
31 .PP
32 .I Name
33 points to the name of the file
34 to be executed; it must not be a directory, and the permissions
35 must allow the current user to execute it
36 (see
37 .IR stat (3)).
38 It should also be a valid binary image, as defined in the
39 .IR a.out (6)
40 for the current machine architecture,
41 or a shell script
42 (see
43 .IR rc (1)).
44 The first line of a
45 shell script must begin with
46 .L #!
47 followed by the name of the program to interpret the file
48 and any initial arguments to that program, for example
49 .IP
50 .EX
51 #!/bin/rc
52 ls | mc
53 .EE
54 .PP
55 When a C program is executed,
56 it is called as follows:
57 .IP
58 .EX
59 void main(int argc, char *argv[])
60 .EE
61 .PP
62 .I Argv
63 is a copy of the array of argument pointers passed to
64 .IR exec ;
65 that array must end in a null pointer, and
66 .I argc
67 is the number of elements before the null pointer.
68 By convention, the first argument should be the name of
69 the program to be executed.
70 .I Execl
71 is like
72 .I exec
73 except that
74 .I argv
75 will be an array of the parameters that follow
76 .I name
77 in the call.  The last argument to
78 .I execl
79 must be a null pointer.
80 .PP
81 For a file beginning
82 .BR #! ,
83 the arguments passed to the program
84 .RB ( /bin/rc
85 in the example above) will be the name of the file being
86 executed, any arguments on the
87 .B #!
88 line, the name of the file again,
89 and finally the second and subsequent arguments given to the original
90 .I exec
91 call.
92 The result honors the two conventions of a program accepting as argument
93 a file to be interpreted and
94 .B argv[0]
95 naming the file being
96 executed.
97 .PP
98 Most attributes of the calling process are carried
99 into the result; in particular,
100 files remain open across
101 .I exec
102 (except those opened with
103 .B OCEXEC
104 OR'd
105 into the open mode; see
106 .IR open (3));
107 and the working directory and environment
108 (see
109 .IR env (3))
110 remain the same.
111 However, a newly
112 .I exec'ed
113 process has no notification handler
114 (see
115 .IR notify (3)).
116 .PP
117 When the new program begins, the global cell
118 .B _clock
119 is set to the address of a cell that keeps approximate time
120 expended by the process at user level.
121 The time is measured in milliseconds but is updated at
122 a system-dependent lower rate.
123 This clock is typically used by the profiler but is available
124 to all programs.
125 .PP
126 The global cell
127 .B _privates
128 points to an array of
129 .B _nprivates
130 elements of per-process private data.
131 This storage is private for each process, even if the processes share data segments.
132 .PP
133 The above conventions apply to C programs; the raw system
134 interface to the new image is as follows:
135 the word pointed to by the stack pointer is
136 .BR argc ;
137 the words beyond that are the zeroth and subsequent elements
138 of
139 .BR argv ,
140 followed by a terminating null pointer; and
141 the return register (e.g.
142 .B R0
143 on the 68020) contains the address of the clock.
144 .SH SOURCE
145 .B /sys/src/libc/9syscall
146 .br
147 .B /sys/src/libc/port/execl.c
148 .SH SEE ALSO
149 .IR prof (1),
150 .IR intro (3),
151 .IR stat (3)
152 .SH DIAGNOSTICS
153 If these functions fail, they return and set
154 .IR errstr .
155 There can be no return from a successful
156 .I exec
157 or
158 .IR execl ;
159 the calling image is lost.