1 .TH EXEC 3
2 .SH NAME
3 exec, execl \- 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 .fi
16 .SH DESCRIPTION
17 .I Exec
18 and
19 .I execl
20 overlay the calling process with the named file, then
21 transfer to the entry point of the image of the file.
22 .PP
23 .I Name
24 points to the name of the file
25 to be executed; it must not be a directory, and the permissions
26 must allow the current user to execute it
27 (see
28 .MR stat (3) ).
29 It should also be a valid binary image, as defined by the local
30 operating system, or a shell script
31 (see
32 .MR rc (1) ).
33 The first line of a
34 shell script must begin with
35 .L #!
36 followed by the name of the program to interpret the file
37 and any initial arguments to that program, for example
38 .IP
39 .EX
40 #!/bin/rc
41 ls | mc
42 .EE
43 .PP
44 When a C program is executed,
45 it is called as follows:
46 .IP
47 .EX
48 void main(int argc, char *argv[])
49 .EE
50 .PP
51 .I Argv
52 is a copy of the array of argument pointers passed to
53 .IR exec ;
54 that array must end in a null pointer, and
55 .I argc
56 is the number of elements before the null pointer.
57 By convention, the first argument should be the name of
58 the program to be executed.
59 .I Execl
60 is like
61 .I exec
62 except that
63 .I argv
64 will be an array of the parameters that follow
65 .I name
66 in the call.  The last argument to
67 .I execl
68 must be a null pointer.
69 .PP
70 For a file beginning
71 .BR #! ,
72 the arguments passed to the program
73 .RB ( /bin/rc
74 in the example above) will be the name of the file being
75 executed, any arguments on the
76 .B #!
77 line, the name of the file again,
78 and finally the second and subsequent arguments given to the original
79 .I exec
80 call.
81 The result honors the two conventions of a program accepting as argument
82 a file to be interpreted and
83 .B argv[0]
84 naming the file being
85 executed.
86 .PP
87 Most attributes of the calling process are carried
88 into the result; in particular,
89 files remain open across
90 .I exec
91 (except those opened with
92 .B OCEXEC
93 OR'd
94 into the open mode; see
95 .MR open (3) );
96 and the working directory and environment
97 (see
98 .MR getenv (3) )
99 remain the same.
100 However, a newly
101 .I exec'ed
102 process has no notification handlers
103 (see
104 .MR notify (3) ).
105 .SH SOURCE
106 .B \*9/src/lib9/exec.c
107 .br
108 .B \*9/src/lib9/execl.c
109 .SH SEE ALSO
110 .MR prof (1) ,
111 .MR intro (3) ,
112 .MR stat (3)
113 .SH DIAGNOSTICS
114 If these functions fail, they return and set
115 .IR errstr .
116 There can be no return from a successful
117 .I exec
118 or
119 .IR execl ;
120 the calling image is lost.
121 .SH BUGS
122 On Unix, unlike on Plan 9,
123 .I exec
124 and
125 .I execl
126 use the user's current path to locate
127 .IR prog .
128 This is a clumsy way to deal with Unix's lack of
129 a union directory for
130 .BR /bin .
131 .PP
132 To avoid name conflicts with the underlying system,
133 .I exec
134 and
135 .I execl
136 are preprocessor macros defined as
137 .I p9exec
138 and
139 .IR p9execl ;
140 see
141 .MR intro (3) .