bsd/man/man3/posix_spawnattr_init.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_init.3
  29 .
  30 .Dd August 22, 2007
  31 .Dt POSIX_SPAWNATTR_INIT 3
  32 .Os "Mac OS X"
  33 .Sh NAME
  34 .Nm posix_spawnattr_init
  35 .Nm posix_spawnattr_destroy
  36 .Nd initialize or destroy a spawn attributes object
  37 .Sh SYNOPSIS
  38 .Fd #include <spawn.h>
  39 .Ft int
  40 .Fo posix_spawnattr_init
  41 .Fa "posix_spawnattr_t *attr"
  42 .Fc
  43 .Ft int
  44 .Fo posix_spawnattr_destroy
  45 .Fa "posix_spawnattr_t *attr"
  46 .Fc
  47 .Sh DESCRIPTION
  48 The
  49 .Fn posix_spawnattr_init
  50 function initializes the object referenced by
  51 .Em attr ,
  52 to an empty set of spawn attributes for subsequent use in a call to
  53 .Xr posix_spawn 2
  54 or
  55 .Xr posix_spawnp 2 .
  56 .Pp
  57 A
  58 .Em posix_spawnattr_t
  59 object is an opaque type that is used to collect set of spawn attributes
  60 specified by calls to
  61 .Xr posix_spawnattr_setflags 3 ,
  62 .Xr posix_spawnattr_setpgroup 3 ,
  63 .Xr posix_spawnattr_setsigdefault 3 ,
  64 .Xr posix_spawnattr_setsigmask 3 ,
  65 .Xr posix_spawnattr_setbinpref_np 3 ,
  66 .Xr posix_spawnattr_setspecialport_np 3 ,
  67 or
  68 .Xr posix_spawnattr_setexceptionports_np 3
  69 such that once the spawn operation is complete, the child process will
  70 have a different set of attributes than the parent.  The order of these
  71 operations is unspecified and may change; programs should not depend on
  72 their ordering.
  73 .Pp
  74 The
  75 .Fn posix_spawnattr_destroy
  76 function destroys the object referenced by
  77 .Em attr
  78 which was previously intialized by
  79 .Fn posix_spawnattr_init ,
  80 returning any resources obtained at the time of initialization to the
  81 system for subsequent reuse.  A
  82 .Em posix_spawnattr_t
  83 may be reinitialized after having been destroyed, but
  84 .Em must not
  85 be reused after destruction, unless it has been reinitialized.
  86 .Sh RETURN VALUES
  87 On success, these functions return 0; on failure they return an error
  88 number from
  89 .In errno.h .
  90 .Sh ERRORS
  91 The
  92 .Fn posix_spawnattr_init
  93 and
  94 .Fn posix_spawnattr_destroy
  95 functions will fail and return an error if:
  96 .Bl -tag -width Er
  97 .\" ==========
  98 .It Bq Er ENOMEM
  99 Insufficient resources to initialize the
 100 .Fa posix_spawnattr_t
 101 object.
 102 .\" ==========
 103 .It Bq Er EINVAL
 104 The
 105 .Fa posix_spawnattr_t
 106 being destroyed is invalid.
 107 .El
 108 .Sh SEE ALSO
 109 .Xr posix_spawn 2 ,
 110 .Xr posix_spawnp 2 ,
 111 .Xr posix_spawnattr_setflags 3 ,
 112 .Xr posix_spawnattr_setpgroup 3 ,
 113 .Xr posix_spawnattr_setsigdefault 3 ,
 114 .Xr posix_spawnattr_setsigmask 3 ,
 115 .Xr posix_spawnattr_setbinpref_np 3 ,
 116 .Xr posix_spawnattr_setspecialport_np 3 ,
 117 .Xr posix_spawnattr_setexceptionports_np 3
 118 .Sh STANDARDS
 119 .St -susv3 [SPN]
 120 .Sh HISTORY
 121 The
 122 .Fn posix_spawn
 123 and
 124 .Fn posix_spawnp
 125 function calls appeared in
 126 .St -susv3 [SPN] .