master
1/* Definitions for POSIX spawn interface.
2 Copyright (C) 2000-2025 Free Software Foundation, Inc.
3 This file is part of the GNU C Library.
4
5 The GNU C Library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) any later version.
9
10 The GNU C Library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Lesser General Public License for more details.
14
15 You should have received a copy of the GNU Lesser General Public
16 License along with the GNU C Library; if not, see
17 <https://www.gnu.org/licenses/>. */
18
19#ifndef _SPAWN_H
20#define _SPAWN_H 1
21
22#include <features.h>
23#include <sched.h>
24#include <sys/types.h>
25#include <bits/types/sigset_t.h>
26
27
28/* Data structure to contain attributes for thread creation. */
29typedef struct
30{
31 short int __flags;
32 pid_t __pgrp;
33 sigset_t __sd;
34 sigset_t __ss;
35 struct sched_param __sp;
36 int __policy;
37 int __cgroup;
38 int __pad[15];
39} posix_spawnattr_t;
40
41
42/* Data structure to contain information about the actions to be
43 performed in the new process with respect to file descriptors. */
44typedef struct
45{
46 int __allocated;
47 int __used;
48 struct __spawn_action *__actions;
49 int __pad[16];
50} posix_spawn_file_actions_t;
51
52
53/* Flags to be set in the `posix_spawnattr_t'. */
54#define POSIX_SPAWN_RESETIDS 0x01
55#define POSIX_SPAWN_SETPGROUP 0x02
56#define POSIX_SPAWN_SETSIGDEF 0x04
57#define POSIX_SPAWN_SETSIGMASK 0x08
58#define POSIX_SPAWN_SETSCHEDPARAM 0x10
59#define POSIX_SPAWN_SETSCHEDULER 0x20
60#ifdef __USE_GNU
61# define POSIX_SPAWN_USEVFORK 0x40
62# define POSIX_SPAWN_SETSID 0x80
63# define POSIX_SPAWN_SETCGROUP 0x100
64#endif
65
66
67__BEGIN_DECLS
68
69/* Spawn a new process executing PATH with the attributes describes in *ATTRP.
70 Before running the process perform the actions described in FILE-ACTIONS.
71
72 This function is a possible cancellation point and therefore not
73 marked with __THROW. */
74extern int posix_spawn (pid_t *__restrict __pid,
75 const char *__restrict __path,
76 const posix_spawn_file_actions_t *__restrict
77 __file_actions,
78 const posix_spawnattr_t *__restrict __attrp,
79 char *const __argv[__restrict_arr],
80 char *const __envp[__restrict_arr])
81 __nonnull ((2, 5));
82
83/* Similar to `posix_spawn' but search for FILE in the PATH.
84
85 This function is a possible cancellation point and therefore not
86 marked with __THROW. */
87extern int posix_spawnp (pid_t *__pid, const char *__file,
88 const posix_spawn_file_actions_t *__file_actions,
89 const posix_spawnattr_t *__attrp,
90 char *const __argv[], char *const __envp[])
91 __nonnull ((2, 5));
92
93
94/* Initialize data structure with attributes for `spawn' to default values. */
95extern int posix_spawnattr_init (posix_spawnattr_t *__attr)
96 __THROW __nonnull ((1));
97
98/* Free resources associated with ATTR. */
99extern int posix_spawnattr_destroy (posix_spawnattr_t *__attr)
100 __THROW __nonnull ((1));
101
102/* Store signal mask for signals with default handling from ATTR in
103 SIGDEFAULT. */
104extern int posix_spawnattr_getsigdefault (const posix_spawnattr_t *
105 __restrict __attr,
106 sigset_t *__restrict __sigdefault)
107 __THROW __nonnull ((1, 2));
108
109/* Set signal mask for signals with default handling in ATTR to SIGDEFAULT. */
110extern int posix_spawnattr_setsigdefault (posix_spawnattr_t *__restrict __attr,
111 const sigset_t *__restrict
112 __sigdefault)
113 __THROW __nonnull ((1, 2));
114
115/* Store signal mask for the new process from ATTR in SIGMASK. */
116extern int posix_spawnattr_getsigmask (const posix_spawnattr_t *__restrict
117 __attr,
118 sigset_t *__restrict __sigmask)
119 __THROW __nonnull ((1, 2));
120
121/* Set signal mask for the new process in ATTR to SIGMASK. */
122extern int posix_spawnattr_setsigmask (posix_spawnattr_t *__restrict __attr,
123 const sigset_t *__restrict __sigmask)
124 __THROW __nonnull ((1, 2));
125
126/* Get flag word from the attribute structure. */
127extern int posix_spawnattr_getflags (const posix_spawnattr_t *__restrict
128 __attr,
129 short int *__restrict __flags)
130 __THROW __nonnull ((1, 2));
131
132/* Store flags in the attribute structure. */
133extern int posix_spawnattr_setflags (posix_spawnattr_t *_attr,
134 short int __flags)
135 __THROW __nonnull ((1));
136
137/* Get process group ID from the attribute structure. */
138extern int posix_spawnattr_getpgroup (const posix_spawnattr_t *__restrict
139 __attr, pid_t *__restrict __pgroup)
140 __THROW __nonnull ((1, 2));
141
142/* Store process group ID in the attribute structure. */
143extern int posix_spawnattr_setpgroup (posix_spawnattr_t *__attr,
144 pid_t __pgroup)
145 __THROW __nonnull ((1));
146
147/* Get scheduling policy from the attribute structure. */
148extern int posix_spawnattr_getschedpolicy (const posix_spawnattr_t *
149 __restrict __attr,
150 int *__restrict __schedpolicy)
151 __THROW __nonnull ((1, 2));
152
153/* Store scheduling policy in the attribute structure. */
154extern int posix_spawnattr_setschedpolicy (posix_spawnattr_t *__attr,
155 int __schedpolicy)
156 __THROW __nonnull ((1));
157
158/* Get scheduling parameters from the attribute structure. */
159extern int posix_spawnattr_getschedparam (const posix_spawnattr_t *
160 __restrict __attr,
161 struct sched_param *__restrict
162 __schedparam)
163 __THROW __nonnull ((1, 2));
164
165/* Store scheduling parameters in the attribute structure. */
166extern int posix_spawnattr_setschedparam (posix_spawnattr_t *__restrict __attr,
167 const struct sched_param *
168 __restrict __schedparam)
169 __THROW __nonnull ((1, 2));
170
171/* Initialize data structure for file attribute for `spawn' call. */
172extern int posix_spawn_file_actions_init (posix_spawn_file_actions_t *
173 __file_actions)
174 __THROW __nonnull ((1));
175
176/* Free resources associated with FILE-ACTIONS. */
177extern int posix_spawn_file_actions_destroy (posix_spawn_file_actions_t *
178 __file_actions)
179 __THROW __nonnull ((1));
180
181/* Add an action to FILE-ACTIONS which tells the implementation to call
182 `open' for the given file during the `spawn' call. */
183extern int posix_spawn_file_actions_addopen (posix_spawn_file_actions_t *
184 __restrict __file_actions,
185 int __fd,
186 const char *__restrict __path,
187 int __oflag, mode_t __mode)
188 __THROW __nonnull ((1, 3));
189
190/* Add an action to FILE-ACTIONS which tells the implementation to call
191 `close' for the given file descriptor during the `spawn' call. */
192extern int posix_spawn_file_actions_addclose (posix_spawn_file_actions_t *
193 __file_actions, int __fd)
194 __THROW __nonnull ((1));
195
196/* Add an action to FILE-ACTIONS which tells the implementation to call
197 `dup2' for the given file descriptors during the `spawn' call. */
198extern int posix_spawn_file_actions_adddup2 (posix_spawn_file_actions_t *
199 __file_actions,
200 int __fd, int __newfd)
201 __THROW __nonnull ((1));
202
203#ifdef __USE_MISC
204/* Add an action changing the directory to PATH during spawn. This
205 affects the subsequent file actions. */
206extern int posix_spawn_file_actions_addchdir_np (posix_spawn_file_actions_t *
207 __restrict __actions,
208 const char *__restrict __path)
209 __THROW __nonnull ((1, 2));
210
211/* Add an action changing the directory to FD during spawn. This
212 affects the subsequent file actions. FD is not duplicated and must
213 be open when the file action is executed. */
214extern int posix_spawn_file_actions_addfchdir_np (posix_spawn_file_actions_t *,
215 int __fd)
216 __THROW __nonnull ((1));
217
218/* Add an action to close all file descriptor greater than or equal to FROM
219 during spawn. This affects the subsequent file actions. */
220extern int
221posix_spawn_file_actions_addclosefrom_np (posix_spawn_file_actions_t *,
222 int __from)
223 __THROW __nonnull ((1));
224
225/* Add an action to set the process group of the foreground process group
226 associated with the terminal TCFD. */
227extern int
228posix_spawn_file_actions_addtcsetpgrp_np (posix_spawn_file_actions_t *,
229 int __tcfd)
230 __THROW __nonnull ((1));
231
232#endif /* __USE_MISC */
233
234__END_DECLS
235
236#include <bits/spawn_ext.h>
237
238#endif /* spawn.h */