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