bsd/man/man3/posix_spawnattr_setflags.3

   1 .\"
   2 .\" Copyright (c) 2000-2016 Apple Inc. All rights reserved.
   3 .\"
   4 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5 .\"
   6 .\" This file contains Original Code and/or Modifications of Original Code
   7 .\" as defined in and that are subject to the Apple Public Source License
   8 .\" Version 2.0 (the 'License'). You may not use this file except in
   9 .\" compliance with the License. The rights granted to you under the License
  10 .\" may not be used to create, or enable the creation or redistribution of,
  11 .\" unlawful or unlicensed copies of an Apple operating system, or to
  12 .\" circumvent, violate, or enable the circumvention or violation of, any
  13 .\" terms of an Apple operating system software license agreement.
  14 .\"
  15 .\" Please obtain a copy of the License at
  16 .\" http://www.opensource.apple.com/apsl/ and read it before using this file.
  17 .\"
  18 .\" The Original Code and all software distributed under the License are
  19 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23 .\" Please see the License for the specific language governing rights and
  24 .\" limitations under the License.
  25 .\"
  26 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27 .\"
  28 .\"     @(#)posix_spawnattr_setflags.3
  29 .
  30 .Dd October 28, 2010
  31 .Dt POSIX_SPAWNATTR_SETFLAGS 3
  32 .Os "Mac OS X"
  33 .Sh NAME
  34 .Nm posix_spawnattr_setflags
  35 .Nm posix_spawnattr_getflags
  36 .Nd get or set flags on a
  37 .Em posix_spawnattr_t
  38 .Sh SYNOPSIS
  39 .Fd #include <spawn.h>
  40 .Ft int
  41 .Fo posix_spawnattr_setflags
  42 .Fa "posix_spawnattr_t *attr"
  43 .Fa "short flags"
  44 .Fc
  45 .Ft int
  46 .Fo posix_spawnattr_getflags
  47 .Fa "const posix_spawnattr_t *restrict attr"
  48 .Fa "short *restrict flags"
  49 .Fc
  50 .Sh DESCRIPTION
  51 The
  52 .Fn posix_spawnattr_setflags
  53 function sets the
  54 .Fa flags
  55 on the attributes object referenced by
  56 .Fa attr .
  57 .Pp
  58 The
  59 .Fn posix_spawnattr_getflags
  60 function retrieves the
  61 .Fa flags
  62 on the attributes object referenced by
  63 .Fa attr .
  64 .Pp
  65 The argument
  66 .Fa flags
  67 is either 0 or a logical OR of one or more of the following flags:
  68 .Bl -tag -width POSIX_SPAWN_START_SUSPENDED
  69 .It Dv POSIX_SPAWN_RESETIDS
  70 If this bit is set, the child process will inherit the real (rather than the effective) user and
  71 group ID of the parent process. NOTE: This flag has no effect when the set-group bit is set on the
  72 process image being spawned.
  73 .It Dv POSIX_SPAWN_SETPGROUP
  74 If this bit is not set, then the child process inherits the parent
  75 process group; if it is set, then the child process will behave as if the
  76 .Xr setpgid 2
  77 function had been called with a
  78 .Fa pid
  79 parameter of 0 and a
  80 .Fa pgid
  81 parameter equal to the value of the spawn-pgroup value of the
  82 .Em posix_spawnattr_t ,
  83 as set by
  84 .Xr posix_spawnattr_setpgroup 3
  85 .It Dv POSIX_SPAWN_SETSIGDEF
  86 Signals set to either be caught or to the default action in the
  87 parent process will also be set to the default action in the child
  88 process.  Signals set to be ignored in the parent process will be
  89 ignored in the child.  However, if this bit is set, then signals in
  90 the
  91 .Em spawn-sigdefault
  92 value of the
  93 .Em posix_spawnattr_t ,
  94 as set by
  95 .Xr posix_spawnattr_setsigdefault 3
  96 which are caught or ignored in the parent will instead be reset to
  97 their default actions in the child.
  98 .It Dv POSIX_SPAWN_SETSIGMASK
  99 If this bit is set, then the initial signal mask of the child process will
 100 be set to the
 101 .Em spawn-sigmask
 102 value of the
 103 .Em posix_spawnattr_t ,
 104 as set by
 105 .Xr posix_spawnattr_setsigmask 3 .
 106 .It Dv POSIX_SPAWN_SETEXEC
 107 .Em Apple Extension :
 108 If this bit is set, rather than returning to the caller,
 109 .Xr posix_spawn 2
 110 and
 111 .Xr posix_spawnp 2
 112 will behave as a more featureful
 113 .Xr execve 2 .
 114 .It Dv POSIX_SPAWN_START_SUSPENDED
 115 .Em Apple Extension :
 116 If this bit is set, then the child process will be created as if it immediately
 117 received a
 118 .Li SIGSTOP
 119 signal, permitting debuggers, profilers, and other programs to manipulate the
 120 process before it begins execution in user space.  This permits, for example,
 121 obtaining exact instruction counts, or debugging very early in
 122 .Xr dyld 1 .
 123 To resume the child process, it must be sent a
 124 .Li SIGCONT
 125 signal.
 126 .It Dv POSIX_SPAWN_CLOEXEC_DEFAULT
 127 .Em Apple Extension :
 128 If this bit is set, then only file descriptors explicitly described by the
 129 .Fa file_actions
 130 argument are available in the spawned process; all of the other file descriptors
 131 are automatically closed in the spawned process.
 132 .El
 133 .Sh RETURN VALUES
 134 On success, these functions return 0; on failure they return an error number
 135 from
 136 .In errno.h .
 137 The
 138 .Fn posix_spawnattr_getflags
 139 function additionally, upon successful completion, makes the value pointed to by
 140 the
 141 .Fa flags
 142 argument equal to the
 143 .Em spawn-flags
 144 attribute of the
 145 .Em posix_spawnattr_t .
 146 .Sh ERRORS
 147 These functions may fail if:
 148 .Bl -tag -width Er
 149 .\" ==========
 150 .It Bq Er EINVAL
 151 The value specified by
 152 .Fa attr
 153 is invalid.
 154 .\" ==========
 155 .It Bq Er EINVAL
 156 The value of
 157 .Fa attr
 158 is invalid.
 159 .El
 160 .Sh SEE ALSO
 161 .Xr posix_spawn 2 ,
 162 .Xr posix_spawnp 2 ,
 163 .Xr posix_spawnattr_init 3 ,
 164 .Xr posix_spawnattr_destroy 3 ,
 165 .Xr posix_spawnattr_setpgroup 3 ,
 166 .Xr posix_spawnattr_setsigdefault 3 ,
 167 .Xr posix_spawnattr_setsigmask 3 ,
 168 .Xr posix_spawn_file_actions_init 3 ,
 169 .Xr setpgid 2 ,
 170 .Xr signal 3 ,
 171 .Xr execve 2 ,
 172 .Xr dyld 1
 173 .Sh STANDARDS
 174 .St -susv3 [SPN]
 175 .Sh HISTORY
 176 The
 177 .Fn posix_spawnattr_setflags
 178 and
 179 .Fn posix_spawnattr_getflags
 180 function calls appeared in
 181 .St -susv3 [SPN] .