posix/spawn.h

   1 /* Definitions for POSIX spawn interface.
   2    Copyright (C) 2000-2023 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.  */
  29 typedef 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 __pad[16];
  38 } posix_spawnattr_t;
  39
  40
  41 /* Data structure to contain information about the actions to be
  42    performed in the new process with respect to file descriptors.  */
  43 typedef struct
  44 {
  45   int __allocated;
  46   int __used;
  47   struct __spawn_action *__actions;
  48   int __pad[16];
  49 } posix_spawn_file_actions_t;
  50
  51
  52 /* Flags to be set in the `posix_spawnattr_t'.  */
  53 #define POSIX_SPAWN_RESETIDS            0x01
  54 #define POSIX_SPAWN_SETPGROUP           0x02
  55 #define POSIX_SPAWN_SETSIGDEF           0x04
  56 #define POSIX_SPAWN_SETSIGMASK          0x08
  57 #define POSIX_SPAWN_SETSCHEDPARAM       0x10
  58 #define POSIX_SPAWN_SETSCHEDULER        0x20
  59 #ifdef __USE_GNU
  60 # define POSIX_SPAWN_USEVFORK           0x40
  61 # define POSIX_SPAWN_SETSID             0x80
  62 #endif
  63
  64
  65 __BEGIN_DECLS
  66
  67 /* Spawn a new process executing PATH with the attributes describes in *ATTRP.
  68    Before running the process perform the actions described in FILE-ACTIONS.
  69
  70    This function is a possible cancellation point and therefore not
  71    marked with __THROW. */
  72 extern int posix_spawn (pid_t *__restrict __pid,
  73                         const char *__restrict __path,
  74                         const posix_spawn_file_actions_t *__restrict
  75                         __file_actions,
  76                         const posix_spawnattr_t *__restrict __attrp,
  77                         char *const __argv[__restrict_arr],
  78                         char *const __envp[__restrict_arr])
  79     __nonnull ((2, 5));
  80
  81 /* Similar to `posix_spawn' but search for FILE in the PATH.
  82
  83    This function is a possible cancellation point and therefore not
  84    marked with __THROW.  */
  85 extern int posix_spawnp (pid_t *__pid, const char *__file,
  86                          const posix_spawn_file_actions_t *__file_actions,
  87                          const posix_spawnattr_t *__attrp,
  88                          char *const __argv[], char *const __envp[])
  89     __nonnull ((2, 5));
  90
  91
  92 /* Initialize data structure with attributes for `spawn' to default values.  */
  93 extern int posix_spawnattr_init (posix_spawnattr_t *__attr)
  94     __THROW __nonnull ((1));
  95
  96 /* Free resources associated with ATTR.  */
  97 extern int posix_spawnattr_destroy (posix_spawnattr_t *__attr)
  98     __THROW __nonnull ((1));
  99
 100 /* Store signal mask for signals with default handling from ATTR in
 101    SIGDEFAULT.  */
 102 extern int posix_spawnattr_getsigdefault (const posix_spawnattr_t *
 103                                           __restrict __attr,
 104                                           sigset_t *__restrict __sigdefault)
 105      __THROW __nonnull ((1, 2));
 106
 107 /* Set signal mask for signals with default handling in ATTR to SIGDEFAULT.  */
 108 extern int posix_spawnattr_setsigdefault (posix_spawnattr_t *__restrict __attr,
 109                                           const sigset_t *__restrict
 110                                           __sigdefault)
 111      __THROW __nonnull ((1, 2));
 112
 113 /* Store signal mask for the new process from ATTR in SIGMASK.  */
 114 extern int posix_spawnattr_getsigmask (const posix_spawnattr_t *__restrict
 115                                        __attr,
 116                                        sigset_t *__restrict __sigmask)
 117     __THROW __nonnull ((1, 2));
 118
 119 /* Set signal mask for the new process in ATTR to SIGMASK.  */
 120 extern int posix_spawnattr_setsigmask (posix_spawnattr_t *__restrict __attr,
 121                                        const sigset_t *__restrict __sigmask)
 122      __THROW __nonnull ((1, 2));
 123
 124 /* Get flag word from the attribute structure.  */
 125 extern int posix_spawnattr_getflags (const posix_spawnattr_t *__restrict
 126                                      __attr,
 127                                      short int *__restrict __flags)
 128      __THROW __nonnull ((1, 2));
 129
 130 /* Store flags in the attribute structure.  */
 131 extern int posix_spawnattr_setflags (posix_spawnattr_t *_attr,
 132                                      short int __flags)
 133      __THROW __nonnull ((1));
 134
 135 /* Get process group ID from the attribute structure.  */
 136 extern int posix_spawnattr_getpgroup (const posix_spawnattr_t *__restrict
 137                                       __attr, pid_t *__restrict __pgroup)
 138      __THROW __nonnull ((1, 2));
 139
 140 /* Store process group ID in the attribute structure.  */
 141 extern int posix_spawnattr_setpgroup (posix_spawnattr_t *__attr,
 142                                       pid_t __pgroup)
 143      __THROW __nonnull ((1));
 144
 145 /* Get scheduling policy from the attribute structure.  */
 146 extern int posix_spawnattr_getschedpolicy (const posix_spawnattr_t *
 147                                            __restrict __attr,
 148                                            int *__restrict __schedpolicy)
 149      __THROW __nonnull ((1, 2));
 150
 151 /* Store scheduling policy in the attribute structure.  */
 152 extern int posix_spawnattr_setschedpolicy (posix_spawnattr_t *__attr,
 153                                            int __schedpolicy)
 154      __THROW __nonnull ((1));
 155
 156 /* Get scheduling parameters from the attribute structure.  */
 157 extern int posix_spawnattr_getschedparam (const posix_spawnattr_t *
 158                                           __restrict __attr,
 159                                           struct sched_param *__restrict
 160                                           __schedparam)
 161      __THROW __nonnull ((1, 2));
 162
 163 /* Store scheduling parameters in the attribute structure.  */
 164 extern int posix_spawnattr_setschedparam (posix_spawnattr_t *__restrict __attr,
 165                                           const struct sched_param *
 166                                           __restrict __schedparam)
 167      __THROW __nonnull ((1, 2));
 168
 169 /* Initialize data structure for file attribute for `spawn' call.  */
 170 extern int posix_spawn_file_actions_init (posix_spawn_file_actions_t *
 171                                           __file_actions)
 172      __THROW __nonnull ((1));
 173
 174 /* Free resources associated with FILE-ACTIONS.  */
 175 extern int posix_spawn_file_actions_destroy (posix_spawn_file_actions_t *
 176                                              __file_actions)
 177      __THROW __nonnull ((1));
 178
 179 /* Add an action to FILE-ACTIONS which tells the implementation to call
 180    `open' for the given file during the `spawn' call.  */
 181 extern int posix_spawn_file_actions_addopen (posix_spawn_file_actions_t *
 182                                              __restrict __file_actions,
 183                                              int __fd,
 184                                              const char *__restrict __path,
 185                                              int __oflag, mode_t __mode)
 186      __THROW __nonnull ((1, 3));
 187
 188 /* Add an action to FILE-ACTIONS which tells the implementation to call
 189    `close' for the given file descriptor during the `spawn' call.  */
 190 extern int posix_spawn_file_actions_addclose (posix_spawn_file_actions_t *
 191                                               __file_actions, int __fd)
 192      __THROW __nonnull ((1));
 193
 194 /* Add an action to FILE-ACTIONS which tells the implementation to call
 195    `dup2' for the given file descriptors during the `spawn' call.  */
 196 extern int posix_spawn_file_actions_adddup2 (posix_spawn_file_actions_t *
 197                                              __file_actions,
 198                                              int __fd, int __newfd)
 199      __THROW __nonnull ((1));
 200
 201 #ifdef __USE_MISC
 202 /* Add an action changing the directory to PATH during spawn.  This
 203    affects the subsequent file actions.  */
 204 extern int posix_spawn_file_actions_addchdir_np (posix_spawn_file_actions_t *
 205                                                  __restrict __actions,
 206                                                  const char *__restrict __path)
 207      __THROW __nonnull ((1, 2));
 208
 209 /* Add an action changing the directory to FD during spawn.  This
 210    affects the subsequent file actions.  FD is not duplicated and must
 211    be open when the file action is executed.  */
 212 extern int posix_spawn_file_actions_addfchdir_np (posix_spawn_file_actions_t *,
 213                                                   int __fd)
 214      __THROW __nonnull ((1));
 215
 216 /* Add an action to close all file descriptor greater than or equal to FROM
 217    during spawn.  This affects the subsequent file actions.  */
 218 extern int
 219 posix_spawn_file_actions_addclosefrom_np (posix_spawn_file_actions_t *,
 220                                           int __from)
 221      __THROW __nonnull ((1));
 222
 223 /* Add an action to set the process group of the forground process group
 224    associated with the terminal TCFD.  */
 225 extern int
 226 posix_spawn_file_actions_addtcsetpgrp_np (posix_spawn_file_actions_t *,
 227                                           int __tcfd)
 228      __THROW __nonnull ((1));
 229
 230 #endif /* __USE_MISC */
 231
 232 __END_DECLS
 233
 234 #endif /* spawn.h */