1 cfa37a7b 2004-04-10 devnull .TH EXEC 3
3 058b0118 2005-01-03 devnull exec, execl \- execute a file
4 cfa37a7b 2004-04-10 devnull .SH SYNOPSIS
5 cfa37a7b 2004-04-10 devnull .B #include <u.h>
7 cfa37a7b 2004-04-10 devnull .B #include <libc.h>
11 cfa37a7b 2004-04-10 devnull int exec(char *name, char* argv[])
14 cfa37a7b 2004-04-10 devnull int execl(char *name, ...)
16 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
20 cfa37a7b 2004-04-10 devnull overlay the calling process with the named file, then
21 cfa37a7b 2004-04-10 devnull transfer to the entry point of the image of the file.
24 cfa37a7b 2004-04-10 devnull points to the name of the file
25 cfa37a7b 2004-04-10 devnull to be executed; it must not be a directory, and the permissions
26 cfa37a7b 2004-04-10 devnull must allow the current user to execute it
28 d32deab1 2020-08-16 rsc .MR stat (3) ).
29 058b0118 2005-01-03 devnull It should also be a valid binary image, as defined by the local
30 058b0118 2005-01-03 devnull operating system, or a shell script
32 d32deab1 2020-08-16 rsc .MR rc (1) ).
33 cfa37a7b 2004-04-10 devnull The first line of a
34 cfa37a7b 2004-04-10 devnull shell script must begin with
36 cfa37a7b 2004-04-10 devnull followed by the name of the program to interpret the file
37 cfa37a7b 2004-04-10 devnull and any initial arguments to that program, for example
40 cfa37a7b 2004-04-10 devnull #!/bin/rc
44 cfa37a7b 2004-04-10 devnull When a C program is executed,
45 cfa37a7b 2004-04-10 devnull it is called as follows:
48 cfa37a7b 2004-04-10 devnull void main(int argc, char *argv[])
52 cfa37a7b 2004-04-10 devnull is a copy of the array of argument pointers passed to
53 cfa37a7b 2004-04-10 devnull .IR exec ;
54 cfa37a7b 2004-04-10 devnull that array must end in a null pointer, and
56 cfa37a7b 2004-04-10 devnull is the number of elements before the null pointer.
57 cfa37a7b 2004-04-10 devnull By convention, the first argument should be the name of
58 cfa37a7b 2004-04-10 devnull the program to be executed.
62 cfa37a7b 2004-04-10 devnull except that
64 cfa37a7b 2004-04-10 devnull will be an array of the parameters that follow
66 cfa37a7b 2004-04-10 devnull in the call. The last argument to
68 cfa37a7b 2004-04-10 devnull must be a null pointer.
70 cfa37a7b 2004-04-10 devnull For a file beginning
72 cfa37a7b 2004-04-10 devnull the arguments passed to the program
73 cfa37a7b 2004-04-10 devnull .RB ( /bin/rc
74 cfa37a7b 2004-04-10 devnull in the example above) will be the name of the file being
75 cfa37a7b 2004-04-10 devnull executed, any arguments on the
77 cfa37a7b 2004-04-10 devnull line, the name of the file again,
78 cfa37a7b 2004-04-10 devnull and finally the second and subsequent arguments given to the original
81 cfa37a7b 2004-04-10 devnull The result honors the two conventions of a program accepting as argument
82 cfa37a7b 2004-04-10 devnull a file to be interpreted and
83 cfa37a7b 2004-04-10 devnull .B argv[0]
84 cfa37a7b 2004-04-10 devnull naming the file being
85 cfa37a7b 2004-04-10 devnull executed.
87 cfa37a7b 2004-04-10 devnull Most attributes of the calling process are carried
88 cfa37a7b 2004-04-10 devnull into the result; in particular,
89 cfa37a7b 2004-04-10 devnull files remain open across
91 cfa37a7b 2004-04-10 devnull (except those opened with
92 cfa37a7b 2004-04-10 devnull .B OCEXEC
94 cfa37a7b 2004-04-10 devnull into the open mode; see
95 d32deab1 2020-08-16 rsc .MR open (3) );
96 cfa37a7b 2004-04-10 devnull and the working directory and environment
98 d32deab1 2020-08-16 rsc .MR getenv (3) )
99 cfa37a7b 2004-04-10 devnull remain the same.
100 cfa37a7b 2004-04-10 devnull However, a newly
101 cfa37a7b 2004-04-10 devnull .I exec'ed
102 058b0118 2005-01-03 devnull process has no notification handlers
104 d32deab1 2020-08-16 rsc .MR notify (3) ).
105 cfa37a7b 2004-04-10 devnull .SH SOURCE
106 c3674de4 2005-01-11 devnull .B \*9/src/lib9/exec.c
108 c3674de4 2005-01-11 devnull .B \*9/src/lib9/execl.c
109 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
110 d32deab1 2020-08-16 rsc .MR prof (1) ,
111 d32deab1 2020-08-16 rsc .MR intro (3) ,
112 d32deab1 2020-08-16 rsc .MR stat (3)
113 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
114 cfa37a7b 2004-04-10 devnull If these functions fail, they return and set
115 cfa37a7b 2004-04-10 devnull .IR errstr .
116 cfa37a7b 2004-04-10 devnull There can be no return from a successful
119 cfa37a7b 2004-04-10 devnull .IR execl ;
120 cfa37a7b 2004-04-10 devnull the calling image is lost.
121 058b0118 2005-01-03 devnull .SH BUGS
122 058b0118 2005-01-03 devnull On Unix, unlike on Plan 9,
125 058b0118 2005-01-03 devnull .I execl
126 058b0118 2005-01-03 devnull use the user's current path to locate
127 058b0118 2005-01-03 devnull .IR prog .
128 058b0118 2005-01-03 devnull This is a clumsy way to deal with Unix's lack of
129 058b0118 2005-01-03 devnull a union directory for
130 058b0118 2005-01-03 devnull .BR /bin .
132 c8b6342d 2005-01-13 devnull To avoid name conflicts with the underlying system,
135 c8b6342d 2005-01-13 devnull .I execl
136 c8b6342d 2005-01-13 devnull are preprocessor macros defined as
137 c8b6342d 2005-01-13 devnull .I p9exec
139 c8b6342d 2005-01-13 devnull .IR p9execl ;
141 d32deab1 2020-08-16 rsc .MR intro (3) .
