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