]>
Commit | Line | Data |
---|---|---|
085d0e35 | 1 | @node Processes, Inter-Process Communication, Program Basics, Top |
7a68c94a | 2 | @c %MENU% How to create processes and run other programs |
28f540f4 RM |
3 | @chapter Processes |
4 | ||
5 | @cindex process | |
6 | @dfn{Processes} are the primitive units for allocation of system | |
7 | resources. Each process has its own address space and (usually) one | |
8 | thread of control. A process executes a program; you can have multiple | |
9 | processes executing the same program, but each process has its own copy | |
10 | of the program within its own address space and executes it | |
11 | independently of the other copies. | |
12 | ||
13 | @cindex child process | |
14 | @cindex parent process | |
15 | Processes are organized hierarchically. Each process has a @dfn{parent | |
16 | process} which explicitly arranged to create it. The processes created | |
17 | by a given parent are called its @dfn{child processes}. A child | |
18 | inherits many of its attributes from the parent process. | |
19 | ||
20 | This chapter describes how a program can create, terminate, and control | |
21 | child processes. Actually, there are three distinct operations | |
22 | involved: creating a new child process, causing the new process to | |
23 | execute a program, and coordinating the completion of the child process | |
24 | with the original program. | |
25 | ||
26 | The @code{system} function provides a simple, portable mechanism for | |
27 | running another program; it does all three steps automatically. If you | |
28 | need more control over the details of how this is done, you can use the | |
29 | primitive functions to do each step individually instead. | |
30 | ||
31 | @menu | |
32 | * Running a Command:: The easy way to run another program. | |
33 | * Process Creation Concepts:: An overview of the hard way to do it. | |
34 | * Process Identification:: How to get the process ID of a process. | |
35 | * Creating a Process:: How to fork a child process. | |
36 | * Executing a File:: How to make a process execute another program. | |
37 | * Process Completion:: How to tell when a child process has completed. | |
f65fd747 | 38 | * Process Completion Status:: How to interpret the status value |
28f540f4 RM |
39 | returned from a child process. |
40 | * BSD Wait Functions:: More functions, for backward compatibility. | |
41 | * Process Creation Example:: A complete example program. | |
42 | @end menu | |
43 | ||
44 | ||
45 | @node Running a Command | |
46 | @section Running a Command | |
47 | @cindex running a command | |
48 | ||
49 | The easy way to run another program is to use the @code{system} | |
50 | function. This function does all the work of running a subprogram, but | |
51 | it doesn't give you much control over the details: you have to wait | |
52 | until the subprogram terminates before you can do anything else. | |
53 | ||
28f540f4 | 54 | @deftypefun int system (const char *@var{command}) |
d08a7e4c | 55 | @standards{ISO, stdlib.h} |
28f540f4 | 56 | @pindex sh |
19f5d29c AO |
57 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} |
58 | @c system @ascuplugin @ascuheap @asulock @aculock @acsmem | |
59 | @c do_system @ascuplugin @ascuheap @asulock @aculock @acsmem | |
60 | @c sigemptyset dup ok | |
61 | @c libc_lock_lock @asulock @aculock | |
62 | @c ADD_REF ok | |
63 | @c sigaction dup ok | |
64 | @c SUB_REF ok | |
65 | @c libc_lock_unlock @aculock | |
66 | @c sigaddset dup ok | |
67 | @c sigprocmask dup ok | |
68 | @c CLEANUP_HANDLER @ascuplugin @ascuheap @acsmem | |
69 | @c libc_cleanup_region_start @ascuplugin @ascuheap @acsmem | |
70 | @c pthread_cleanup_push_defer @ascuplugin @ascuheap @acsmem | |
2b517425 | 71 | @c __pthread_testcancel @ascuplugin @ascuheap @acsmem |
19f5d29c AO |
72 | @c CANCEL_ENABLED_AND_CANCELED ok |
73 | @c do_cancel @ascuplugin @ascuheap @acsmem | |
74 | @c cancel_handler ok | |
75 | @c kill syscall ok | |
76 | @c waitpid dup ok | |
77 | @c libc_lock_lock ok | |
78 | @c sigaction dup ok | |
79 | @c libc_lock_unlock ok | |
80 | @c FORK ok | |
81 | @c clone syscall ok | |
82 | @c waitpid dup ok | |
83 | @c CLEANUP_RESET ok | |
84 | @c libc_cleanup_region_end ok | |
85 | @c pthread_cleanup_pop_restore ok | |
86 | @c SINGLE_THREAD_P ok | |
87 | @c LIBC_CANCEL_ASYNC @ascuplugin @ascuheap @acsmem | |
88 | @c libc_enable_asynccancel @ascuplugin @ascuheap @acsmem | |
19f5d29c AO |
89 | @c do_cancel dup @ascuplugin @ascuheap @acsmem |
90 | @c LIBC_CANCEL_RESET ok | |
91 | @c libc_disable_asynccancel ok | |
92 | @c lll_futex_wait dup ok | |
1f77f049 JM |
93 | This function executes @var{command} as a shell command. In @theglibc{}, |
94 | it always uses the default shell @code{sh} to run the command. | |
28f540f4 RM |
95 | In particular, it searches the directories in @code{PATH} to find |
96 | programs to execute. The return value is @code{-1} if it wasn't | |
97 | possible to create the shell process, and otherwise is the status of the | |
98 | shell process. @xref{Process Completion}, for details on how this | |
99 | status code can be interpreted. | |
100 | ||
bafb8ee9 UD |
101 | If the @var{command} argument is a null pointer, a return value of zero |
102 | indicates that no command processor is available. | |
cc3fa755 | 103 | |
0bc93a2f | 104 | This function is a cancellation point in multi-threaded programs. This |
dfd2257a UD |
105 | is a problem if the thread allocates some resources (like memory, file |
106 | descriptors, semaphores or whatever) at the time @code{system} is | |
107 | called. If the thread gets canceled these resources stay allocated | |
108 | until the program ends. To avoid this calls to @code{system} should be | |
0bc93a2f | 109 | protected using cancellation handlers. |
dfd2257a UD |
110 | @c ref pthread_cleanup_push / pthread_cleanup_pop |
111 | ||
28f540f4 RM |
112 | @pindex stdlib.h |
113 | The @code{system} function is declared in the header file | |
114 | @file{stdlib.h}. | |
115 | @end deftypefun | |
116 | ||
117 | @strong{Portability Note:} Some C implementations may not have any | |
118 | notion of a command processor that can execute other programs. You can | |
119 | determine whether a command processor exists by executing | |
120 | @w{@code{system (NULL)}}; if the return value is nonzero, a command | |
121 | processor is available. | |
122 | ||
123 | The @code{popen} and @code{pclose} functions (@pxref{Pipe to a | |
124 | Subprocess}) are closely related to the @code{system} function. They | |
125 | allow the parent process to communicate with the standard input and | |
126 | output channels of the command being executed. | |
127 | ||
128 | @node Process Creation Concepts | |
129 | @section Process Creation Concepts | |
130 | ||
131 | This section gives an overview of processes and of the steps involved in | |
132 | creating a process and making it run another program. | |
133 | ||
28f540f4 RM |
134 | @cindex creating a process |
135 | @cindex forking a process | |
136 | @cindex child process | |
137 | @cindex parent process | |
e361dc04 FW |
138 | @cindex subprocess |
139 | A new processes is created when one of the functions | |
c32c868a AZ |
140 | @code{posix_spawn}, @code{fork}, @code{_Fork} or @code{vfork} is called. |
141 | (The @code{system} and @code{popen} also create new processes internally.) | |
e361dc04 FW |
142 | Due to the name of the @code{fork} function, the act of creating a new |
143 | process is sometimes called @dfn{forking} a process. Each new process | |
144 | (the @dfn{child process} or @dfn{subprocess}) is allocated a process | |
145 | ID, distinct from the process ID of the parent process. @xref{Process | |
146 | Identification}. | |
28f540f4 RM |
147 | |
148 | After forking a child process, both the parent and child processes | |
149 | continue to execute normally. If you want your program to wait for a | |
150 | child process to finish executing before continuing, you must do this | |
151 | explicitly after the fork operation, by calling @code{wait} or | |
152 | @code{waitpid} (@pxref{Process Completion}). These functions give you | |
153 | limited information about why the child terminated---for example, its | |
154 | exit status code. | |
155 | ||
156 | A newly forked child process continues to execute the same program as | |
c32c868a AZ |
157 | its parent process, at the point where the @code{fork} or @code{_Fork} |
158 | call returns. You can use the return value from @code{fork} or | |
159 | @code{_Fork} to tell whether the program is running in the parent process | |
160 | or the child. | |
28f540f4 RM |
161 | |
162 | @cindex process image | |
163 | Having several processes run the same program is only occasionally | |
164 | useful. But the child can execute another program using one of the | |
165 | @code{exec} functions; see @ref{Executing a File}. The program that the | |
166 | process is executing is called its @dfn{process image}. Starting | |
167 | execution of a new program causes the process to forget all about its | |
168 | previous process image; when the new program exits, the process exits | |
169 | too, instead of returning to the previous process image. | |
170 | ||
171 | @node Process Identification | |
172 | @section Process Identification | |
173 | ||
e361dc04 FW |
174 | @cindex process ID |
175 | Each process is named by a @dfn{process ID} number, a value of type | |
176 | @code{pid_t}. A process ID is allocated to each process when it is | |
177 | created. Process IDs are reused over time. The lifetime of a process | |
178 | ends when the parent process of the corresponding process waits on the | |
179 | process ID after the process has terminated. @xref{Process | |
180 | Completion}. (The parent process can arrange for such waiting to | |
181 | happen implicitly.) A process ID uniquely identifies a process only | |
182 | during the lifetime of the process. As a rule of thumb, this means | |
183 | that the process must still be running. | |
184 | ||
185 | Process IDs can also denote process groups and sessions. | |
186 | @xref{Job Control}. | |
187 | ||
188 | @cindex thread ID | |
189 | @cindex task ID | |
190 | @cindex thread group | |
191 | On Linux, threads created by @code{pthread_create} also receive a | |
192 | @dfn{thread ID}. The thread ID of the initial (main) thread is the | |
193 | same as the process ID of the entire process. Thread IDs for | |
194 | subsequently created threads are distinct. They are allocated from | |
195 | the same numbering space as process IDs. Process IDs and thread IDs | |
196 | are sometimes also referred to collectively as @dfn{task IDs}. In | |
197 | contrast to processes, threads are never waited for explicitly, so a | |
198 | thread ID becomes eligible for reuse as soon as a thread exits or is | |
199 | canceled. This is true even for joinable threads, not just detached | |
200 | threads. Threads are assigned to a @dfn{thread group}. In | |
201 | @theglibc{} implementation running on Linux, the process ID is the | |
202 | thread group ID of all threads in the process. | |
203 | ||
204 | You can get the process ID of a process by calling @code{getpid}. The | |
205 | function @code{getppid} returns the process ID of the parent of the | |
206 | current process (this is also known as the @dfn{parent process ID}). | |
207 | Your program should include the header files @file{unistd.h} and | |
28f540f4 RM |
208 | @file{sys/types.h} to use these functions. |
209 | @pindex sys/types.h | |
210 | @pindex unistd.h | |
211 | ||
28f540f4 | 212 | @deftp {Data Type} pid_t |
d08a7e4c | 213 | @standards{POSIX.1, sys/types.h} |
28f540f4 | 214 | The @code{pid_t} data type is a signed integer type which is capable |
1f77f049 | 215 | of representing a process ID. In @theglibc{}, this is an @code{int}. |
28f540f4 RM |
216 | @end deftp |
217 | ||
28f540f4 | 218 | @deftypefun pid_t getpid (void) |
d08a7e4c | 219 | @standards{POSIX.1, unistd.h} |
19f5d29c | 220 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
221 | The @code{getpid} function returns the process ID of the current process. |
222 | @end deftypefun | |
223 | ||
28f540f4 | 224 | @deftypefun pid_t getppid (void) |
d08a7e4c | 225 | @standards{POSIX.1, unistd.h} |
19f5d29c | 226 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
227 | The @code{getppid} function returns the process ID of the parent of the |
228 | current process. | |
229 | @end deftypefun | |
230 | ||
1d0fc213 FW |
231 | @deftypefun pid_t gettid (void) |
232 | @standards{Linux, unistd.h} | |
233 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
234 | The @code{gettid} function returns the thread ID of the current | |
235 | thread. The returned value is obtained from the Linux kernel and is | |
236 | not subject to caching. See the discussion of thread IDs above, | |
237 | especially regarding reuse of the IDs of threads which have exited. | |
238 | ||
239 | This function is specific to Linux. | |
240 | @end deftypefun | |
241 | ||
28f540f4 RM |
242 | @node Creating a Process |
243 | @section Creating a Process | |
244 | ||
245 | The @code{fork} function is the primitive for creating a process. | |
246 | It is declared in the header file @file{unistd.h}. | |
247 | @pindex unistd.h | |
248 | ||
28f540f4 | 249 | @deftypefun pid_t fork (void) |
d08a7e4c | 250 | @standards{POSIX.1, unistd.h} |
19f5d29c | 251 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{}}@acunsafe{@aculock{}}} |
c32c868a AZ |
252 | @c The posix/fork.c implementation iterates over the fork_handlers |
253 | @c using a lock. It then takes the IO_list lock, resets the thread-local | |
254 | @c pid, and runs fork. The parent releases the lock, and runs parent | |
255 | @c handlers, and unlocks the internal lock. The child bumps the fork | |
256 | @c generation, sets the thread-local pid, resets cpu clocks, initializes | |
257 | @c the robust mutex list, the stream locks, the IO_list lock, the dynamic | |
258 | @c loader lock, runs the child handlers, reseting ref counters to 1, and | |
19f5d29c AO |
259 | @c initializes the fork lock. These are all safe, unless atfork |
260 | @c handlers themselves are unsafe. | |
28f540f4 RM |
261 | The @code{fork} function creates a new process. |
262 | ||
263 | If the operation is successful, there are then both parent and child | |
264 | processes and both see @code{fork} return, but with different values: it | |
265 | returns a value of @code{0} in the child process and returns the child's | |
266 | process ID in the parent process. | |
267 | ||
268 | If process creation failed, @code{fork} returns a value of @code{-1} in | |
269 | the parent process. The following @code{errno} error conditions are | |
270 | defined for @code{fork}: | |
271 | ||
272 | @table @code | |
273 | @item EAGAIN | |
274 | There aren't enough system resources to create another process, or the | |
275 | user already has too many processes running. This means exceeding the | |
276 | @code{RLIMIT_NPROC} resource limit, which can usually be increased; | |
277 | @pxref{Limits on Resources}. | |
278 | ||
279 | @item ENOMEM | |
280 | The process requires more space than the system can supply. | |
281 | @end table | |
282 | @end deftypefun | |
283 | ||
284 | The specific attributes of the child process that differ from the | |
285 | parent process are: | |
286 | ||
287 | @itemize @bullet | |
288 | @item | |
289 | The child process has its own unique process ID. | |
290 | ||
291 | @item | |
292 | The parent process ID of the child process is the process ID of its | |
293 | parent process. | |
294 | ||
295 | @item | |
296 | The child process gets its own copies of the parent process's open file | |
297 | descriptors. Subsequently changing attributes of the file descriptors | |
298 | in the parent process won't affect the file descriptors in the child, | |
299 | and vice versa. @xref{Control Operations}. However, the file position | |
300 | associated with each descriptor is shared by both processes; | |
301 | @pxref{File Position}. | |
302 | ||
303 | @item | |
304 | The elapsed processor times for the child process are set to zero; | |
305 | see @ref{Processor Time}. | |
306 | ||
307 | @item | |
308 | The child doesn't inherit file locks set by the parent process. | |
309 | @c !!! flock locks shared | |
310 | @xref{Control Operations}. | |
311 | ||
312 | @item | |
313 | The child doesn't inherit alarms set by the parent process. | |
314 | @xref{Setting an Alarm}. | |
315 | ||
316 | @item | |
317 | The set of pending signals (@pxref{Delivery of Signal}) for the child | |
318 | process is cleared. (The child process inherits its mask of blocked | |
319 | signals and signal actions from the parent process.) | |
f65fd747 | 320 | @end itemize |
28f540f4 | 321 | |
c32c868a AZ |
322 | @deftypefun pid_t _Fork (void) |
323 | @standards{GNU, unistd.h} | |
324 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
325 | The @code{_Fork} function is similar to @code{fork}, but it does not invoke | |
326 | any callbacks registered with @code{pthread_atfork}, nor does it reset | |
327 | any internal state or locks (such as the @code{malloc} locks). In the | |
328 | new subprocess, only async-signal-safe functions may be called, such as | |
329 | @code{dup2} or @code{execve}. | |
330 | ||
331 | The @code{_Fork} function is an async-signal-safe replacement of @code{fork}. | |
332 | It is a GNU extension. | |
333 | ||
334 | @end deftypefun | |
28f540f4 | 335 | |
28f540f4 | 336 | @deftypefun pid_t vfork (void) |
d08a7e4c | 337 | @standards{BSD, unistd.h} |
19f5d29c AO |
338 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{}}@acunsafe{@aculock{}}} |
339 | @c The vfork implementation proper is a safe syscall, but it may fall | |
340 | @c back to fork if the vfork syscall is not available. | |
440d13e2 UD |
341 | The @code{vfork} function is similar to @code{fork} but on some systems |
342 | it is more efficient; however, there are restrictions you must follow to | |
28f540f4 RM |
343 | use it safely. |
344 | ||
440d13e2 UD |
345 | While @code{fork} makes a complete copy of the calling process's address |
346 | space and allows both the parent and child to execute independently, | |
347 | @code{vfork} does not make this copy. Instead, the child process | |
348 | created with @code{vfork} shares its parent's address space until it | |
349 | calls @code{_exit} or one of the @code{exec} functions. In the | |
28f540f4 RM |
350 | meantime, the parent process suspends execution. |
351 | ||
352 | You must be very careful not to allow the child process created with | |
353 | @code{vfork} to modify any global data or even local variables shared | |
354 | with the parent. Furthermore, the child process cannot return from (or | |
355 | do a long jump out of) the function that called @code{vfork}! This | |
356 | would leave the parent process's control information very confused. If | |
357 | in doubt, use @code{fork} instead. | |
358 | ||
1f77f049 JM |
359 | Some operating systems don't really implement @code{vfork}. @Theglibc{} |
360 | permits you to use @code{vfork} on all systems, but actually | |
28f540f4 RM |
361 | executes @code{fork} if @code{vfork} isn't available. If you follow |
362 | the proper precautions for using @code{vfork}, your program will still | |
363 | work even if the system uses @code{fork} instead. | |
364 | @end deftypefun | |
365 | ||
366 | @node Executing a File | |
367 | @section Executing a File | |
368 | @cindex executing a file | |
369 | @cindex @code{exec} functions | |
370 | ||
371 | This section describes the @code{exec} family of functions, for executing | |
372 | a file as a process image. You can use these functions to make a child | |
373 | process execute a new program after it has been forked. | |
374 | ||
17c389fc | 375 | To see the effects of @code{exec} from the point of view of the called |
88197030 | 376 | program, see @ref{Program Basics}. |
17c389fc | 377 | |
28f540f4 RM |
378 | @pindex unistd.h |
379 | The functions in this family differ in how you specify the arguments, | |
380 | but otherwise they all do the same thing. They are declared in the | |
381 | header file @file{unistd.h}. | |
382 | ||
28f540f4 | 383 | @deftypefun int execv (const char *@var{filename}, char *const @var{argv}@t{[]}) |
d08a7e4c | 384 | @standards{POSIX.1, unistd.h} |
19f5d29c | 385 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
386 | The @code{execv} function executes the file named by @var{filename} as a |
387 | new process image. | |
388 | ||
389 | The @var{argv} argument is an array of null-terminated strings that is | |
390 | used to provide a value for the @code{argv} argument to the @code{main} | |
391 | function of the program to be executed. The last element of this array | |
392 | must be a null pointer. By convention, the first element of this array | |
393 | is the file name of the program sans directory names. @xref{Program | |
394 | Arguments}, for full details on how programs can access these arguments. | |
395 | ||
396 | The environment for the new process image is taken from the | |
397 | @code{environ} variable of the current process image; see | |
398 | @ref{Environment Variables}, for information about environments. | |
399 | @end deftypefun | |
400 | ||
28f540f4 | 401 | @deftypefun int execl (const char *@var{filename}, const char *@var{arg0}, @dots{}) |
d08a7e4c | 402 | @standards{POSIX.1, unistd.h} |
19f5d29c | 403 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} |
28f540f4 RM |
404 | This is similar to @code{execv}, but the @var{argv} strings are |
405 | specified individually instead of as an array. A null pointer must be | |
406 | passed as the last such argument. | |
407 | @end deftypefun | |
408 | ||
28f540f4 | 409 | @deftypefun int execve (const char *@var{filename}, char *const @var{argv}@t{[]}, char *const @var{env}@t{[]}) |
d08a7e4c | 410 | @standards{POSIX.1, unistd.h} |
19f5d29c | 411 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
412 | This is similar to @code{execv}, but permits you to specify the environment |
413 | for the new program explicitly as the @var{env} argument. This should | |
f65fd747 | 414 | be an array of strings in the same format as for the @code{environ} |
28f540f4 RM |
415 | variable; see @ref{Environment Access}. |
416 | @end deftypefun | |
417 | ||
6771af11 FW |
418 | @deftypefun int fexecve (int @var{fd}, char *const @var{argv}@t{[]}, char *const @var{env}@t{[]}) |
419 | @standards{POSIX.1, unistd.h} | |
420 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
2a8682ea | 421 | This is similar to @code{execve}, but instead of identifying the program |
6771af11 FW |
422 | executable by its pathname, the file descriptor @var{fd} is used. The |
423 | descriptor must have been opened with the @code{O_RDONLY} flag or (on | |
424 | Linux) the @code{O_PATH} flag. | |
425 | ||
426 | On Linux, @code{fexecve} can fail with an error of @code{ENOSYS} if | |
427 | @file{/proc} has not been mounted and the kernel lacks support for the | |
428 | underlying @code{execveat} system call. | |
429 | @end deftypefun | |
430 | ||
d1b10e78 | 431 | @deftypefun int execle (const char *@var{filename}, const char *@var{arg0}, @dots{}, char *const @var{env}@t{[]}) |
d08a7e4c | 432 | @standards{POSIX.1, unistd.h} |
19f5d29c | 433 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} |
28f540f4 RM |
434 | This is similar to @code{execl}, but permits you to specify the |
435 | environment for the new program explicitly. The environment argument is | |
436 | passed following the null pointer that marks the last @var{argv} | |
437 | argument, and should be an array of strings in the same format as for | |
438 | the @code{environ} variable. | |
439 | @end deftypefun | |
440 | ||
28f540f4 | 441 | @deftypefun int execvp (const char *@var{filename}, char *const @var{argv}@t{[]}) |
d08a7e4c | 442 | @standards{POSIX.1, unistd.h} |
19f5d29c | 443 | @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} |
28f540f4 RM |
444 | The @code{execvp} function is similar to @code{execv}, except that it |
445 | searches the directories listed in the @code{PATH} environment variable | |
446 | (@pxref{Standard Environment}) to find the full file name of a | |
447 | file from @var{filename} if @var{filename} does not contain a slash. | |
448 | ||
449 | This function is useful for executing system utility programs, because | |
450 | it looks for them in the places that the user has chosen. Shells use it | |
451 | to run the commands that users type. | |
452 | @end deftypefun | |
453 | ||
28f540f4 | 454 | @deftypefun int execlp (const char *@var{filename}, const char *@var{arg0}, @dots{}) |
d08a7e4c | 455 | @standards{POSIX.1, unistd.h} |
19f5d29c | 456 | @safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} |
28f540f4 RM |
457 | This function is like @code{execl}, except that it performs the same |
458 | file name searching as the @code{execvp} function. | |
459 | @end deftypefun | |
460 | ||
461 | The size of the argument list and environment list taken together must | |
a7a93d50 JM |
462 | not be greater than @code{ARG_MAX} bytes. @xref{General Limits}. On |
463 | @gnuhurdsystems{}, the size (which compares against @code{ARG_MAX}) | |
28f540f4 RM |
464 | includes, for each string, the number of characters in the string, plus |
465 | the size of a @code{char *}, plus one, rounded up to a multiple of the | |
466 | size of a @code{char *}. Other systems may have somewhat different | |
467 | rules for counting. | |
468 | ||
469 | These functions normally don't return, since execution of a new program | |
470 | causes the currently executing program to go away completely. A value | |
471 | of @code{-1} is returned in the event of a failure. In addition to the | |
472 | usual file name errors (@pxref{File Name Errors}), the following | |
473 | @code{errno} error conditions are defined for these functions: | |
474 | ||
475 | @table @code | |
476 | @item E2BIG | |
477 | The combined size of the new program's argument list and environment | |
a7a93d50 | 478 | list is larger than @code{ARG_MAX} bytes. @gnuhurdsystems{} have no |
28f540f4 RM |
479 | specific limit on the argument list size, so this error code cannot |
480 | result, but you may get @code{ENOMEM} instead if the arguments are too | |
481 | big for available memory. | |
482 | ||
483 | @item ENOEXEC | |
484 | The specified file can't be executed because it isn't in the right format. | |
485 | ||
486 | @item ENOMEM | |
487 | Executing the specified file requires more storage than is available. | |
488 | @end table | |
489 | ||
490 | If execution of the new file succeeds, it updates the access time field | |
491 | of the file as if the file had been read. @xref{File Times}, for more | |
492 | details about access times of files. | |
493 | ||
494 | The point at which the file is closed again is not specified, but | |
495 | is at some point before the process exits or before another process | |
496 | image is executed. | |
497 | ||
498 | Executing a new process image completely changes the contents of memory, | |
499 | copying only the argument and environment strings to new locations. But | |
500 | many other attributes of the process are unchanged: | |
501 | ||
502 | @itemize @bullet | |
503 | @item | |
504 | The process ID and the parent process ID. @xref{Process Creation Concepts}. | |
505 | ||
506 | @item | |
507 | Session and process group membership. @xref{Concepts of Job Control}. | |
508 | ||
509 | @item | |
510 | Real user ID and group ID, and supplementary group IDs. @xref{Process | |
511 | Persona}. | |
512 | ||
513 | @item | |
514 | Pending alarms. @xref{Setting an Alarm}. | |
515 | ||
516 | @item | |
517 | Current working directory and root directory. @xref{Working | |
a7a93d50 | 518 | Directory}. On @gnuhurdsystems{}, the root directory is not copied when |
28f540f4 RM |
519 | executing a setuid program; instead the system default root directory |
520 | is used for the new program. | |
521 | ||
522 | @item | |
523 | File mode creation mask. @xref{Setting Permissions}. | |
524 | ||
525 | @item | |
526 | Process signal mask; see @ref{Process Signal Mask}. | |
527 | ||
528 | @item | |
529 | Pending signals; see @ref{Blocking Signals}. | |
530 | ||
531 | @item | |
532 | Elapsed processor time associated with the process; see @ref{Processor Time}. | |
533 | @end itemize | |
534 | ||
535 | If the set-user-ID and set-group-ID mode bits of the process image file | |
536 | are set, this affects the effective user ID and effective group ID | |
537 | (respectively) of the process. These concepts are discussed in detail | |
538 | in @ref{Process Persona}. | |
539 | ||
540 | Signals that are set to be ignored in the existing process image are | |
541 | also set to be ignored in the new process image. All other signals are | |
542 | set to the default action in the new process image. For more | |
543 | information about signals, see @ref{Signal Handling}. | |
544 | ||
545 | File descriptors open in the existing process image remain open in the | |
546 | new process image, unless they have the @code{FD_CLOEXEC} | |
547 | (close-on-exec) flag set. The files that remain open inherit all | |
9cbcfebd | 548 | attributes of the open file descriptors from the existing process image, |
28f540f4 RM |
549 | including file locks. File descriptors are discussed in @ref{Low-Level I/O}. |
550 | ||
551 | Streams, by contrast, cannot survive through @code{exec} functions, | |
552 | because they are located in the memory of the process itself. The new | |
553 | process image has no streams except those it creates afresh. Each of | |
554 | the streams in the pre-@code{exec} process image has a descriptor inside | |
555 | it, and these descriptors do survive through @code{exec} (provided that | |
556 | they do not have @code{FD_CLOEXEC} set). The new process image can | |
557 | reconnect these to new streams using @code{fdopen} (@pxref{Descriptors | |
558 | and Streams}). | |
559 | ||
560 | @node Process Completion | |
561 | @section Process Completion | |
562 | @cindex process completion | |
563 | @cindex waiting for completion of child process | |
564 | @cindex testing exit status of child process | |
565 | ||
566 | The functions described in this section are used to wait for a child | |
567 | process to terminate or stop, and determine its status. These functions | |
568 | are declared in the header file @file{sys/wait.h}. | |
569 | @pindex sys/wait.h | |
570 | ||
28f540f4 | 571 | @deftypefun pid_t waitpid (pid_t @var{pid}, int *@var{status-ptr}, int @var{options}) |
d08a7e4c | 572 | @standards{POSIX.1, sys/wait.h} |
19f5d29c | 573 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
574 | The @code{waitpid} function is used to request status information from a |
575 | child process whose process ID is @var{pid}. Normally, the calling | |
576 | process is suspended until the child process makes status information | |
577 | available by terminating. | |
578 | ||
579 | Other values for the @var{pid} argument have special interpretations. A | |
580 | value of @code{-1} or @code{WAIT_ANY} requests status information for | |
581 | any child process; a value of @code{0} or @code{WAIT_MYPGRP} requests | |
582 | information for any child process in the same process group as the | |
583 | calling process; and any other negative value @minus{} @var{pgid} | |
584 | requests information for any child process whose process group ID is | |
585 | @var{pgid}. | |
586 | ||
587 | If status information for a child process is available immediately, this | |
588 | function returns immediately without waiting. If more than one eligible | |
589 | child process has status information available, one of them is chosen | |
590 | randomly, and its status is returned immediately. To get the status | |
591 | from the other eligible child processes, you need to call @code{waitpid} | |
592 | again. | |
593 | ||
594 | The @var{options} argument is a bit mask. Its value should be the | |
595 | bitwise OR (that is, the @samp{|} operator) of zero or more of the | |
596 | @code{WNOHANG} and @code{WUNTRACED} flags. You can use the | |
597 | @code{WNOHANG} flag to indicate that the parent process shouldn't wait; | |
598 | and the @code{WUNTRACED} flag to request status information from stopped | |
599 | processes as well as processes that have terminated. | |
600 | ||
601 | The status information from the child process is stored in the object | |
602 | that @var{status-ptr} points to, unless @var{status-ptr} is a null pointer. | |
603 | ||
0bc93a2f | 604 | This function is a cancellation point in multi-threaded programs. This |
dfd2257a UD |
605 | is a problem if the thread allocates some resources (like memory, file |
606 | descriptors, semaphores or whatever) at the time @code{waitpid} is | |
607 | called. If the thread gets canceled these resources stay allocated | |
608 | until the program ends. To avoid this calls to @code{waitpid} should be | |
0bc93a2f | 609 | protected using cancellation handlers. |
dfd2257a UD |
610 | @c ref pthread_cleanup_push / pthread_cleanup_pop |
611 | ||
28f540f4 | 612 | The return value is normally the process ID of the child process whose |
3c20b9b6 UD |
613 | status is reported. If there are child processes but none of them is |
614 | waiting to be noticed, @code{waitpid} will block until one is. However, | |
615 | if the @code{WNOHANG} option was specified, @code{waitpid} will return | |
616 | zero instead of blocking. | |
617 | ||
618 | If a specific PID to wait for was given to @code{waitpid}, it will | |
619 | ignore all other children (if any). Therefore if there are children | |
620 | waiting to be noticed but the child whose PID was specified is not one | |
621 | of them, @code{waitpid} will block or return zero as described above. | |
622 | ||
623 | A value of @code{-1} is returned in case of error. The following | |
624 | @code{errno} error conditions are defined for this function: | |
28f540f4 RM |
625 | |
626 | @table @code | |
627 | @item EINTR | |
628 | The function was interrupted by delivery of a signal to the calling | |
629 | process. @xref{Interrupted Primitives}. | |
630 | ||
631 | @item ECHILD | |
632 | There are no child processes to wait for, or the specified @var{pid} | |
633 | is not a child of the calling process. | |
634 | ||
635 | @item EINVAL | |
636 | An invalid value was provided for the @var{options} argument. | |
637 | @end table | |
638 | @end deftypefun | |
639 | ||
640 | These symbolic constants are defined as values for the @var{pid} argument | |
641 | to the @code{waitpid} function. | |
642 | ||
643 | @comment Extra blank lines make it look better. | |
2fe82ca6 | 644 | @vtable @code |
28f540f4 RM |
645 | @item WAIT_ANY |
646 | ||
647 | This constant macro (whose value is @code{-1}) specifies that | |
648 | @code{waitpid} should return status information about any child process. | |
649 | ||
650 | ||
651 | @item WAIT_MYPGRP | |
652 | This constant (with value @code{0}) specifies that @code{waitpid} should | |
653 | return status information about any child process in the same process | |
654 | group as the calling process. | |
2fe82ca6 | 655 | @end vtable |
28f540f4 RM |
656 | |
657 | These symbolic constants are defined as flags for the @var{options} | |
658 | argument to the @code{waitpid} function. You can bitwise-OR the flags | |
659 | together to obtain a value to use as the argument. | |
660 | ||
2fe82ca6 | 661 | @vtable @code |
28f540f4 RM |
662 | @item WNOHANG |
663 | ||
664 | This flag specifies that @code{waitpid} should return immediately | |
665 | instead of waiting, if there is no child process ready to be noticed. | |
666 | ||
667 | @item WUNTRACED | |
668 | ||
669 | This flag specifies that @code{waitpid} should report the status of any | |
670 | child processes that have been stopped as well as those that have | |
671 | terminated. | |
2fe82ca6 | 672 | @end vtable |
28f540f4 | 673 | |
28f540f4 | 674 | @deftypefun pid_t wait (int *@var{status-ptr}) |
d08a7e4c | 675 | @standards{POSIX.1, sys/wait.h} |
19f5d29c | 676 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
677 | This is a simplified version of @code{waitpid}, and is used to wait |
678 | until any one child process terminates. The call: | |
679 | ||
680 | @smallexample | |
681 | wait (&status) | |
682 | @end smallexample | |
683 | ||
684 | @noindent | |
685 | is exactly equivalent to: | |
686 | ||
687 | @smallexample | |
688 | waitpid (-1, &status, 0) | |
689 | @end smallexample | |
dfd2257a | 690 | |
0bc93a2f | 691 | This function is a cancellation point in multi-threaded programs. This |
dfd2257a UD |
692 | is a problem if the thread allocates some resources (like memory, file |
693 | descriptors, semaphores or whatever) at the time @code{wait} is | |
694 | called. If the thread gets canceled these resources stay allocated | |
695 | until the program ends. To avoid this calls to @code{wait} should be | |
0bc93a2f | 696 | protected using cancellation handlers. |
dfd2257a | 697 | @c ref pthread_cleanup_push / pthread_cleanup_pop |
28f540f4 RM |
698 | @end deftypefun |
699 | ||
28f540f4 | 700 | @deftypefun pid_t wait4 (pid_t @var{pid}, int *@var{status-ptr}, int @var{options}, struct rusage *@var{usage}) |
d08a7e4c | 701 | @standards{BSD, sys/wait.h} |
19f5d29c | 702 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
703 | If @var{usage} is a null pointer, @code{wait4} is equivalent to |
704 | @code{waitpid (@var{pid}, @var{status-ptr}, @var{options})}. | |
705 | ||
706 | If @var{usage} is not null, @code{wait4} stores usage figures for the | |
707 | child process in @code{*@var{rusage}} (but only if the child has | |
708 | terminated, not if it has stopped). @xref{Resource Usage}. | |
709 | ||
710 | This function is a BSD extension. | |
711 | @end deftypefun | |
712 | ||
713 | Here's an example of how to use @code{waitpid} to get the status from | |
714 | all child processes that have terminated, without ever waiting. This | |
715 | function is designed to be a handler for @code{SIGCHLD}, the signal that | |
716 | indicates that at least one child process has terminated. | |
717 | ||
718 | @smallexample | |
719 | @group | |
720 | void | |
721 | sigchld_handler (int signum) | |
722 | @{ | |
f9d6455b UD |
723 | int pid, status, serrno; |
724 | serrno = errno; | |
28f540f4 RM |
725 | while (1) |
726 | @{ | |
727 | pid = waitpid (WAIT_ANY, &status, WNOHANG); | |
728 | if (pid < 0) | |
729 | @{ | |
730 | perror ("waitpid"); | |
731 | break; | |
732 | @} | |
733 | if (pid == 0) | |
734 | break; | |
735 | notice_termination (pid, status); | |
736 | @} | |
f9d6455b | 737 | errno = serrno; |
28f540f4 RM |
738 | @} |
739 | @end group | |
740 | @end smallexample | |
741 | ||
742 | @node Process Completion Status | |
743 | @section Process Completion Status | |
744 | ||
745 | If the exit status value (@pxref{Program Termination}) of the child | |
746 | process is zero, then the status value reported by @code{waitpid} or | |
747 | @code{wait} is also zero. You can test for other kinds of information | |
748 | encoded in the returned status value using the following macros. | |
749 | These macros are defined in the header file @file{sys/wait.h}. | |
750 | @pindex sys/wait.h | |
751 | ||
28f540f4 | 752 | @deftypefn Macro int WIFEXITED (int @var{status}) |
d08a7e4c | 753 | @standards{POSIX.1, sys/wait.h} |
19f5d29c | 754 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
755 | This macro returns a nonzero value if the child process terminated |
756 | normally with @code{exit} or @code{_exit}. | |
757 | @end deftypefn | |
758 | ||
28f540f4 | 759 | @deftypefn Macro int WEXITSTATUS (int @var{status}) |
d08a7e4c | 760 | @standards{POSIX.1, sys/wait.h} |
19f5d29c | 761 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
762 | If @code{WIFEXITED} is true of @var{status}, this macro returns the |
763 | low-order 8 bits of the exit status value from the child process. | |
764 | @xref{Exit Status}. | |
765 | @end deftypefn | |
766 | ||
28f540f4 | 767 | @deftypefn Macro int WIFSIGNALED (int @var{status}) |
d08a7e4c | 768 | @standards{POSIX.1, sys/wait.h} |
19f5d29c | 769 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
770 | This macro returns a nonzero value if the child process terminated |
771 | because it received a signal that was not handled. | |
772 | @xref{Signal Handling}. | |
773 | @end deftypefn | |
774 | ||
28f540f4 | 775 | @deftypefn Macro int WTERMSIG (int @var{status}) |
d08a7e4c | 776 | @standards{POSIX.1, sys/wait.h} |
19f5d29c | 777 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
778 | If @code{WIFSIGNALED} is true of @var{status}, this macro returns the |
779 | signal number of the signal that terminated the child process. | |
780 | @end deftypefn | |
781 | ||
28f540f4 | 782 | @deftypefn Macro int WCOREDUMP (int @var{status}) |
d08a7e4c | 783 | @standards{BSD, sys/wait.h} |
19f5d29c | 784 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
785 | This macro returns a nonzero value if the child process terminated |
786 | and produced a core dump. | |
787 | @end deftypefn | |
788 | ||
28f540f4 | 789 | @deftypefn Macro int WIFSTOPPED (int @var{status}) |
d08a7e4c | 790 | @standards{POSIX.1, sys/wait.h} |
19f5d29c | 791 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
792 | This macro returns a nonzero value if the child process is stopped. |
793 | @end deftypefn | |
794 | ||
28f540f4 | 795 | @deftypefn Macro int WSTOPSIG (int @var{status}) |
d08a7e4c | 796 | @standards{POSIX.1, sys/wait.h} |
19f5d29c | 797 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
798 | If @code{WIFSTOPPED} is true of @var{status}, this macro returns the |
799 | signal number of the signal that caused the child process to stop. | |
800 | @end deftypefn | |
801 | ||
802 | ||
803 | @node BSD Wait Functions | |
b49ab5f4 | 804 | @section BSD Process Wait Function |
28f540f4 | 805 | |
b49ab5f4 FW |
806 | @Theglibc{} also provides the @code{wait3} function for compatibility |
807 | with BSD. This function is declared in @file{sys/wait.h}. It is the | |
808 | predecessor to @code{wait4}, which is more flexible. @code{wait3} is | |
809 | now obsolete. | |
28f540f4 RM |
810 | @pindex sys/wait.h |
811 | ||
b49ab5f4 | 812 | @deftypefun pid_t wait3 (int *@var{status-ptr}, int @var{options}, struct rusage *@var{usage}) |
d08a7e4c | 813 | @standards{BSD, sys/wait.h} |
19f5d29c | 814 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
815 | If @var{usage} is a null pointer, @code{wait3} is equivalent to |
816 | @code{waitpid (-1, @var{status-ptr}, @var{options})}. | |
817 | ||
818 | If @var{usage} is not null, @code{wait3} stores usage figures for the | |
819 | child process in @code{*@var{rusage}} (but only if the child has | |
820 | terminated, not if it has stopped). @xref{Resource Usage}. | |
821 | @end deftypefun | |
822 | ||
823 | @node Process Creation Example | |
824 | @section Process Creation Example | |
825 | ||
826 | Here is an example program showing how you might write a function | |
827 | similar to the built-in @code{system}. It executes its @var{command} | |
828 | argument using the equivalent of @samp{sh -c @var{command}}. | |
829 | ||
830 | @smallexample | |
831 | #include <stddef.h> | |
832 | #include <stdlib.h> | |
833 | #include <unistd.h> | |
834 | #include <sys/types.h> | |
835 | #include <sys/wait.h> | |
836 | ||
837 | /* @r{Execute the command using this shell program.} */ | |
838 | #define SHELL "/bin/sh" | |
839 | ||
840 | @group | |
f65fd747 | 841 | int |
28f540f4 RM |
842 | my_system (const char *command) |
843 | @{ | |
844 | int status; | |
845 | pid_t pid; | |
846 | @end group | |
847 | ||
848 | pid = fork (); | |
849 | if (pid == 0) | |
850 | @{ | |
851 | /* @r{This is the child process. Execute the shell command.} */ | |
852 | execl (SHELL, SHELL, "-c", command, NULL); | |
853 | _exit (EXIT_FAILURE); | |
854 | @} | |
855 | else if (pid < 0) | |
856 | /* @r{The fork failed. Report failure.} */ | |
857 | status = -1; | |
858 | else | |
859 | /* @r{This is the parent process. Wait for the child to complete.} */ | |
860 | if (waitpid (pid, &status, 0) != pid) | |
861 | status = -1; | |
862 | return status; | |
863 | @} | |
864 | @end smallexample | |
865 | ||
866 | @comment Yes, this example has been tested. | |
867 | ||
868 | There are a couple of things you should pay attention to in this | |
869 | example. | |
870 | ||
871 | Remember that the first @code{argv} argument supplied to the program | |
872 | represents the name of the program being executed. That is why, in the | |
873 | call to @code{execl}, @code{SHELL} is supplied once to name the program | |
f65fd747 | 874 | to execute and a second time to supply a value for @code{argv[0]}. |
28f540f4 RM |
875 | |
876 | The @code{execl} call in the child process doesn't return if it is | |
877 | successful. If it fails, you must do something to make the child | |
878 | process terminate. Just returning a bad status code with @code{return} | |
879 | would leave two processes running the original program. Instead, the | |
880 | right behavior is for the child process to report failure to its parent | |
881 | process. | |
882 | ||
883 | Call @code{_exit} to accomplish this. The reason for using @code{_exit} | |
884 | instead of @code{exit} is to avoid flushing fully buffered streams such | |
885 | as @code{stdout}. The buffers of these streams probably contain data | |
886 | that was copied from the parent process by the @code{fork}, data that | |
887 | will be output eventually by the parent process. Calling @code{exit} in | |
888 | the child would output the data twice. @xref{Termination Internals}. |