Commit | Line | Data |
---|---|---|
6db60273 KM |
1 | .\" Copyright (c) 1983 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
2265b4e1 | 5 | .\" @(#)exec.3 6.2 (Berkeley) %G% |
6db60273 | 6 | .\" |
81f3396d | 7 | .TH EXECL 3 "" |
6db60273 KM |
8 | .UC 5 |
9 | .SH NAME | |
2265b4e1 | 10 | execl, execv, execle, execlp, execvp, exec, execve, exect, environ \- execute a file |
6db60273 KM |
11 | .SH SYNOPSIS |
12 | .nf | |
13 | .B execl(name, arg0, arg1, ..., argn, 0) | |
14 | .B char *name, *arg0, *arg1, ..., *argn; | |
15 | .PP | |
16 | .B execv(name, argv) | |
17 | .B char *name, *argv[]; | |
18 | .PP | |
19 | .B "execle(name, arg0, arg1, ..., argn, 0, envp)" | |
20 | .B "char *name, *arg0, *arg1, ..., *argn, *envp[];" | |
21 | .PP | |
22 | .B "exect(name, argv, envp) | |
23 | .B "char *name, *argv[], *envp[]; | |
24 | .PP | |
25 | .B extern char **environ; | |
26 | .fi | |
27 | .SH DESCRIPTION | |
28 | These routines provide various interfaces to the | |
29 | .I execve | |
30 | system call. Refer to | |
31 | .IR execve (2) | |
32 | for a description of their properties; only | |
33 | brief descriptions are provided here. | |
34 | .PP | |
35 | .I Exec | |
36 | in all its forms | |
37 | overlays the calling process with the named file, then | |
38 | transfers to the | |
39 | entry point of the core image of the file. | |
40 | There can be no return from a successful exec; the calling | |
41 | core image is lost. | |
42 | .PP | |
43 | The | |
44 | .I name | |
45 | argument | |
46 | is a pointer to the name of the file | |
47 | to be executed. | |
48 | The pointers | |
49 | .IR arg [ 0 ], | |
50 | .IR arg [ 1 "] ..." | |
51 | address null-terminated strings. | |
52 | Conventionally | |
53 | .IR arg [ 0 ] | |
54 | is the name of the | |
55 | file. | |
56 | .PP | |
57 | Two interfaces are available. | |
58 | .I execl | |
59 | is useful when a known file with known arguments is | |
60 | being called; | |
61 | the arguments to | |
62 | .I execl | |
63 | are the character strings | |
64 | constituting the file and the arguments; | |
65 | the first argument is conventionally | |
66 | the same as the file name (or its last component). | |
67 | A 0 argument must end the argument list. | |
68 | .PP | |
69 | The | |
70 | .I execv | |
71 | version is useful when the number of arguments is unknown | |
72 | in advance; | |
73 | the arguments to | |
74 | .I execv | |
75 | are the name of the file to be | |
76 | executed and a vector of strings containing | |
77 | the arguments. | |
78 | The last argument string must be followed | |
79 | by a 0 pointer. | |
80 | .PP | |
81 | The | |
82 | .I exect | |
83 | version is used when the executed file is to be | |
84 | manipulated with | |
85 | .IR ptrace (2). | |
86 | The program is forced to single step a single | |
87 | instruction giving the parent an opportunity to | |
88 | manipulate its state. On the VAX-11 this is done | |
89 | by setting the trace bit in the process status | |
90 | longword. | |
91 | .PP | |
92 | When a C program is executed, | |
93 | it is called as follows: | |
94 | .PP | |
95 | .nf | |
96 | main(argc, argv, envp) | |
97 | int argc; | |
98 | char **argv, **envp; | |
99 | .fi | |
100 | .PP | |
101 | where | |
102 | .I argc | |
103 | is the argument count | |
104 | and | |
105 | .I argv | |
106 | is an array of character pointers | |
107 | to the arguments themselves. | |
108 | As indicated, | |
109 | .I argc | |
110 | is conventionally at least one | |
111 | and the first member of the array points to a | |
112 | string containing the name of the file. | |
113 | .PP | |
114 | .I Argv | |
115 | is directly usable in another | |
116 | .I execv | |
117 | because | |
118 | .IR argv [ argc ] | |
119 | is 0. | |
120 | .PP | |
121 | .I Envp | |
122 | is a pointer to an array of strings that constitute | |
123 | the | |
124 | .I environment | |
125 | of the process. | |
126 | Each string consists of a name, an \*(lq=\*(rq, and a null-terminated value. | |
127 | The array of pointers is terminated by a null pointer. | |
128 | The shell | |
129 | .IR sh (1) | |
130 | passes an environment entry for each global shell variable | |
131 | defined when the program is called. | |
132 | See | |
133 | .IR environ (7) | |
134 | for some conventionally | |
135 | used names. | |
136 | The C run-time start-off routine places a copy of | |
137 | .I envp | |
138 | in the global cell | |
139 | .IR environ , | |
140 | which is used | |
141 | by | |
142 | .I execv | |
143 | and | |
144 | .I execl | |
145 | to pass the environment to any subprograms executed by the | |
146 | current program. | |
147 | .PP | |
148 | .I Execlp | |
149 | and | |
150 | .I execvp | |
151 | are called with the same arguments as | |
152 | .I execl | |
153 | and | |
154 | .IR execv , | |
155 | but duplicate the shell's actions in searching for an executable | |
156 | file in a list of directories. | |
157 | The directory list is obtained from the environment. | |
158 | .SH FILES | |
159 | .ta \w'/bin/sh 'u | |
160 | /bin/sh shell, invoked if command file found | |
161 | by | |
162 | .I execlp | |
163 | or | |
164 | .I execvp | |
165 | .SH "SEE ALSO" | |
166 | execve(2), | |
167 | fork(2), | |
168 | environ(7), | |
169 | csh(1) | |
170 | .SH DIAGNOSTICS | |
171 | If the file cannot be found, | |
172 | if it is not executable, | |
173 | if it does not start with a valid magic number (see | |
174 | .IR a.out (5)), | |
175 | if maximum memory is exceeded, | |
176 | or if the arguments require too much space, | |
177 | a return | |
178 | constitutes the diagnostic; | |
179 | the return value is \-1. | |
180 | Even for the super-user, | |
181 | at least one of the execute-permission bits must be set for | |
182 | a file to be executed. | |
183 | .SH BUGS | |
184 | If | |
185 | .I execvp | |
186 | is called to execute a file that turns out to be a shell | |
187 | command file, | |
188 | and if it is impossible to execute the shell, | |
189 | the values of | |
190 | .I argv[0] | |
191 | and | |
192 | .I argv[\-1] | |
193 | will be modified before return. |