source: rtems-docs/posix-users/process_creation_and_execution.rst @ 8741d2c

Last change on this file since 8741d2c was 8741d2c, checked in by Joel Sherrill <joel@…>, on 09/06/22 at 22:31:18

posix-users/process_creation_and_execution.rst: Update pthread_atfork()

Updates #4713.

  • Property mode set to 100644
File size: 7.2 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 1988, 2002 On-Line Applications Research Corporation (OAR)
4
5Process Creation and Execution Manager
6######################################
7
8Introduction
9============
10
11The process creation and execution manager provides the functionality
12associated with the creation and termination of processes.
13
14The directives provided by the process creation and execution manager are:
15
16- fork_ - Create a Process
17
18- execl_ - Execute a File
19
20- execv_ - Execute a File
21
22- execle_ - Execute a File
23
24- execve_ - Execute a File
25
26- execlp_ - Execute a File
27
28- execvp_ - Execute a File
29
30- pthread_atfork_ - Register Fork Handlers
31
32- wait_ - Wait for Process Termination
33
34- waitpid_ - Wait for Process Termination
35
36- `_exit`_ - Terminate a Process
37
38Background
39==========
40
41POSIX process functionality can not be completely supported by RTEMS.  This is
42because RTEMS provides no memory protection and implements a *single process,
43multi-threaded execution model*.  In this light, RTEMS provides none of the
44routines that are associated with the creation of new processes.  However,
45since the entire RTEMS application (e.g. executable) is logically a single
46POSIX process, RTEMS is able to provide implementations of many operations on
47processes.  The rule of thumb is that those routines provide a meaningful
48result.  For example, ``getpid()`` returns the node number.
49
50Operations
51==========
52
53The only functionality method defined by this manager which is supported by
54RTEMS is the ``_exit`` service.  The implementation of ``_exit`` shuts the
55application down and is equivalent to invoking either ``exit`` or
56``rtems_shutdown_executive``.
57
58Directives
59==========
60
61This section details the process creation and execution manager's directives.
62A subsection is dedicated to each of this manager's directives and describes
63the calling sequence, related constants, usage, and status codes.
64
65.. _fork:
66
67fork - Create a Process
68-----------------------
69.. index:: fork
70.. index:: create a process
71
72**CALLING SEQUENCE:**
73
74.. code-block:: c
75
76    #include <sys/types.h>
77    int fork( void );
78
79**STATUS CODES:**
80
81.. list-table::
82 :class: rtems-table
83
84 * - ``ENOSYS``
85   - This routine is not supported by RTEMS.
86
87**DESCRIPTION:**
88
89This routine is not supported by RTEMS.
90
91**NOTES:**
92
93NONE
94
95.. _execl:
96
97execl - Execute a File
98----------------------
99.. index:: execl
100.. index:: execute a file
101
102**CALLING SEQUENCE:**
103
104.. code-block:: c
105
106    int execl(
107        const char *path,
108        const char *arg,
109        ...
110    );
111
112**STATUS CODES:**
113
114.. list-table::
115 :class: rtems-table
116
117 * - ``ENOSYS``
118   - This routine is not supported by RTEMS.
119
120**DESCRIPTION:**
121
122This routine is not supported by RTEMS.
123
124**NOTES:**
125
126NONE
127
128.. _execv:
129
130execv - Execute a File
131----------------------
132.. index:: execv
133.. index:: execute a file
134
135**CALLING SEQUENCE:**
136
137.. code-block:: c
138
139    int execv(
140        const char *path,
141        char const *argv[],
142        ...
143    );
144
145**STATUS CODES:**
146
147.. list-table::
148 :class: rtems-table
149
150 * - ``ENOSYS``
151   - This routine is not supported by RTEMS.
152
153**DESCRIPTION:**
154
155This routine is not supported by RTEMS.
156
157**NOTES:**
158
159NONE
160
161.. _execle:
162
163execle - Execute a File
164-----------------------
165.. index:: execle
166.. index:: execute a file
167
168**CALLING SEQUENCE:**
169
170.. code-block:: c
171
172    int execle(
173        const char *path,
174        const char *arg,
175        ...
176    );
177
178**STATUS CODES:**
179
180.. list-table::
181 :class: rtems-table
182
183 * - ``ENOSYS``
184   - This routine is not supported by RTEMS.
185
186**DESCRIPTION:**
187
188This routine is not supported by RTEMS.
189
190**NOTES:**
191
192NONE
193
194.. _execve:
195
196execve - Execute a File
197-----------------------
198.. index:: execve
199.. index:: execute a file
200
201**CALLING SEQUENCE:**
202
203.. code-block:: c
204
205    int execve(
206        const char *path,
207        char *const argv[],
208        char *const envp[]
209    );
210
211**STATUS CODES:**
212
213.. list-table::
214 :class: rtems-table
215
216 * - ``ENOSYS``
217   - This routine is not supported by RTEMS.
218
219**DESCRIPTION:**
220
221This routine is not supported by RTEMS.
222
223**NOTES:**
224
225NONE
226
227.. _execlp:
228
229execlp - Execute a File
230-----------------------
231.. index:: execlp
232.. index:: execute a file
233
234**CALLING SEQUENCE:**
235
236.. code-block:: c
237
238    int execlp(
239        const char *file,
240        const char *arg,
241        ...
242    );
243
244**STATUS CODES:**
245
246.. list-table::
247 :class: rtems-table
248
249 * - ``ENOSYS``
250   - This routine is not supported by RTEMS.
251
252**DESCRIPTION:**
253
254This routine is not supported by RTEMS.
255
256**NOTES:**
257
258NONE
259
260.. _execvp:
261
262execvp - Execute a File
263-----------------------
264.. index:: execvp
265.. index:: execute a file
266
267**CALLING SEQUENCE:**
268
269.. code-block:: c
270
271    int execvp(
272        const char *file,
273        char *const argv[],
274        ...
275    );
276
277**STATUS CODES:**
278
279.. list-table::
280 :class: rtems-table
281
282 * - ``ENOSYS``
283   - This routine is not supported by RTEMS.
284
285**DESCRIPTION:**
286
287This routine is not supported by RTEMS.
288
289**NOTES:**
290
291NONE
292
293.. _pthread_atfork:
294
295pthread_atfork - Register Fork Handlers
296---------------------------------------
297.. index:: pthread_atfork
298.. index:: register fork handlers
299
300**CALLING SEQUENCE:**
301
302.. code-block:: c
303
304    #include <sys/types.h>
305    int pthread_atfork(
306        void (*prepare)(void),
307        void (*parent)(void),
308        void (*child)(void)
309    );
310
311**STATUS CODES:**
312
313.. list-table::
314 :class: rtems-table
315
316 * - ``0``
317   - This routine is a non-functional stub.
318
319**DESCRIPTION:**
320
321This routine is non-functional stub.
322
323**NOTES:**
324
325The POSIX specification for ``pthread_atfork()`` does not address the behavior
326when in a single process environment. Originally, the RTEMS implementation
327returned -1 and set errno to ``ENOSYS``. This was an arbitrary decision
328part with no basis from the wider POSIX community. The FACE Technical
329Standard includes profiles without multiple process support and defined
330the behavior in a single process environment to return 0. Logically, the
331application can register atfork handlers but they will never be invoked.
332
333.. _wait:
334
335wait - Wait for Process Termination
336-----------------------------------
337.. index:: wait
338.. index:: wait for process termination
339
340**CALLING SEQUENCE:**
341
342.. code-block:: c
343
344    #include <sys/types.h>
345    #include <sys/wait.h>
346    int wait(
347        int *stat_loc
348    );
349
350**STATUS CODES:**
351
352.. list-table::
353 
354
355 * - ``ENOSYS``
356   - This routine is not supported by RTEMS.
357
358**DESCRIPTION:**
359
360This routine is not supported by RTEMS.
361
362**NOTES:**
363
364NONE
365
366.. _waitpid:
367
368waitpid - Wait for Process Termination
369--------------------------------------
370.. index:: waitpid
371.. index:: wait for process termination
372
373**CALLING SEQUENCE:**
374
375.. code-block:: c
376
377    int wait(
378        pid_t  pid,
379        int   *stat_loc,
380        int    options
381    );
382
383**STATUS CODES:**
384
385.. list-table::
386 :class: rtems-table
387
388 * - ``ENOSYS``
389   - This routine is not supported by RTEMS.
390
391**DESCRIPTION:**
392
393This routine is not supported by RTEMS.
394
395**NOTES:**
396
397NONE
398
399.. _\_exit:
400
401_exit - Terminate a Process
402---------------------------
403.. index:: _exit
404.. index:: terminate a process
405
406**CALLING SEQUENCE:**
407
408.. code-block:: c
409
410    void _exit(
411        int status
412    );
413
414**STATUS CODES:**
415
416NONE
417
418**DESCRIPTION:**
419
420The ``_exit()`` function terminates the calling process.
421
422**NOTES:**
423
424In RTEMS, a process is equivalent to the entire application on a single
425processor. Invoking this service terminates the application.
Note: See TracBrowser for help on using the repository browser.