bsd/man/man3/posix_spawnattr_setflags.3

   1 .\"
   2 .\" Copyright (c) 2000-2007 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 August 22, 2007
  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 the set group bit is set on the process image being spawned, this
  71 bit has no effect; otherwise, if not set, the child process will
  72 inherit the effective group ID of the parent process, and if set, the
  73 child process will inherit the real group ID of the parent process.
  74 .It Dv POSIX_SPAWN_SETPGROUP
  75 If this bit is not set, then the child process inherits the parent
  76 process group; if set, then the child process shall behave as if the
  77 .Xr setpgid 2
  78 function had been called with a
  79 .Fa pid
  80 parameter of 0 and a
  81 .Fa pgid
  82 parameter equal to the value of the spawn-pgroup value of the
  83 .Em posix_spawnattr_t ,
  84 as set by
  85 .Xr posix_spawnattr_setpgroup 3
  86 .It Dv POSIX_SPAWN_SETSIGDEF
  87 Signals set to to either be caught or to the default action in the
  88 parent process will also be set to the default action in the child
  89 process.  Signals set to be ignored in the parent process will be
  90 ignored in the child.  However, if this bit is set, then signals in
  91 the
  92 .Em spawn-sigdefault
  93 value of the
  94 .Em posix_spawnattr_t ,
  95 as set by
  96 .Xr posix_spawnattr_setsigdefault 3
  97 which are caught or ignored in the parent will instead be reset to
  98 their default actions in the child.
  99 .It Dv POSIX_SPAWN_SETSIGMASK
 100 If this bit is set, then the initial signal mask of the child process will
 101 be set to the
 102 .Em spawn-sigmask
 103 value of the
 104 .Em posix_spawnattr_t ,
 105 as set by
 106 .Xr posix_spawnattr_setsigmask 3 .
 107 .It Dv POSIX_SPAWN_SETEXEC
 108 .Em Apple Extension :
 109 If this bit is set, rather than returning to the caller,
 110 .Xr posix_spawn 2
 111 and
 112 .Xr posix_spawnp 2
 113 will behave as a more featureful
 114 .Xr execve 2 .
 115 .It Dv POSIX_SPAWN_START_SUSPENDED
 116 .Em Apple Extension :
 117 If this bit is set, then the child process will be created with its task
 118 suspended, permitting debuggers, profilers, and other programs to
 119 manipulate the process before it begins execution in user space.  This
 120 permits, for example, obtaining exact instruction counts, or debugging
 121 very early in
 122 .Xr dyld 1 .
 123 .El
 124 .Sh RETURN VALUES
 125 On success, these functions return 0; on failure they return an error
 126 number from
 127 .In errno.h .
 128 The
 129 .Fn posix_spawnattr_getflags
 130 additionally, upon successful completion, modifies the value pointed to be the
 131 .Fa attr
 132 argument by making it equal to the
 133 .Em spawn-flags
 134 attribute of the
 135 .Em posix_spawnattr_t .
 136 .Sh ERRORS
 137 These functions may fail if:
 138 .Bl -tag -width Er
 139 .\" ==========
 140 .It Bq Er EINVAL
 141 The value specified by
 142 .Fa attr
 143 is invalid.
 144 .\" ==========
 145 .It Bq Er EINVAL
 146 The value of
 147 .Fa attr
 148 is invalid.
 149 .El
 150 .Sh SEE ALSO
 151 .Xr posix_spawn 2 ,
 152 .Xr posix_spawnp 2 ,
 153 .Xr posix_spawnattr_init 3 ,
 154 .Xr posix_spawnattr_destroy 3 ,
 155 .Xr posix_spawnattr_setpgroup 3 ,
 156 .Xr posix_spawnattr_setsigdefault 3 ,
 157 .Xr posix_spawnattr_setsigmask 3 ,
 158 .Xr setpgid 2 ,
 159 .Xr execve 2 ,
 160 .Xr dyld 1
 161 .Sh STANDARDS
 162 .St -susv3 [SPN]
 163 .Sh HISTORY
 164 The
 165 .Fn posix_spawnattr_setflags
 166 and
 167 .Fn posix_spawnattr_getflags
 168 function calls appeared in
 169 .St -susv3 [SPN] .