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 __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.  */
  44 typedef 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. */
  74 extern 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.  */
  87 extern 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.  */
  95 extern int posix_spawnattr_init (posix_spawnattr_t *__attr)
  96     __THROW __nonnull ((1));
  97
  98 /* Free resources associated with ATTR.  */
  99 extern 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.  */
 104 extern 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.  */
 110 extern 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.  */
 116 extern 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.  */
 122 extern 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.  */
 127 extern 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.  */
 133 extern 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.  */
 138 extern 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.  */
 143 extern 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.  */
 148 extern 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.  */
 154 extern int posix_spawnattr_setschedpolicy (posix_spawnattr_t *__attr,
 155                                            int __schedpolicy)
 156      __THROW __nonnull ((1));
 157
 158 /* Get scheduling parameters from the attribute structure.  */
 159 extern 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.  */
 166 extern 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.  */
 172 extern 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.  */
 177 extern 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.  */
 183 extern 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.  */
 192 extern 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.  */
 198 extern 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.  */
 206 extern 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.  */
 214 extern 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.  */
 220 extern int
 221 posix_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.  */
 227 extern int
 228 posix_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 */