bsd/man/man3/posix_spawn_file_actions_addclose.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_addclose.3
  29 .
  30 .Dd August 22, 2007
  31 .Dt POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE 3
  32 .Os "Mac OS X"
  33 .Sh NAME
  34 .Nm posix_spawn_file_actions_addclose
  35 .Nm posix_spawn_file_actions_addopen
  36 .Nd add open or close actions to a
  37 .Em posix_spawn_file_actions_t
  38 .Sh SYNOPSIS
  39 .Fd #include <spawn.h>
  40 .Ft int
  41 .Fo posix_spawn_file_actions_addclose
  42 .Fa "posix_spawn_file_actions_t *file_actions"
  43 .Fa "int filedes"
  44 .Fc
  45 .Ft int
  46 .Fo posix_spawn_file_actions_addopen
  47 .Fa "posix_spawn_file_actions_t *restrict file_actions"
  48 .Fa "int filedes"
  49 .Fa "const char *restrict path"
  50 .Fa "int oflag"
  51 .Fa "mode_t mode"
  52 .Fc
  53 .Ft int
  54 .Fo posix_spawn_file_actions_adddup2
  55 .Fa "posix_spawn_file_actions_t *file_actions"
  56 .Fa "int filedes"
  57 .Fa "int newfiledes"
  58 .Fc
  59 .Sh DESCRIPTION
  60 The
  61 .Fn posix_spawn_file_actions_addclose
  62 function adds a close operation to the list of operations associated with
  63 the object referenced by
  64 .Em file_actions ,
  65 for subsequent use in a call to
  66 .Xr posix_spawn 2
  67 or
  68 .Xr posix_spawnp 2 .
  69 The descriptor referred to by
  70 .Em filedes
  71 is closed as if
  72 .Fn close
  73 had been called on it prior to the new child process
  74 starting execution.
  75 .Pp
  76 The
  77 .Fn posix_spawn_file_actions_addopen
  78 function adds an open operation to the list of operations associated with
  79 the object referenced by
  80 .Em file_actions ,
  81 for subsequent use in a call to
  82 .Xr posix_spawn 2
  83 or
  84 .Xr posix_spawnp 2 .
  85 The descriptor referred to by
  86 .Em filedes
  87 is opened using the
  88 .Em path ,
  89 .Em oflag ,
  90 and
  91 .Em mode
  92 arguments as if
  93 .Fn open
  94 had been called on it prior to the new child process
  95 starting execution.  The string
  96 .Em path
  97 is copied by the
  98 .Fn posix_spawn_file_actions_addopen
  99 function during this process, so storage need not be persistent in the
 100 caller.
 101 .Pp
 102 The
 103 .Fn posix_spawn_file_actions_adddup2
 104 function adds a dup2 operation to the list of operations associated with
 105 the object referenced by
 106 .Em file_actions ,
 107 for subsequent use in a call to
 108 .Xr posix_spawn 2
 109 or
 110 .Xr posix_spawnp 2 .
 111 The descriptor referred to by
 112 .Em newfiledes
 113 is created as if
 114 .Fn dup2
 115 had been called on
 116 .Em filedes
 117 prior to the new child process starting execution.
 118 .Sh RETURN VALUES
 119 On success, these functions return 0; on failure they return an error
 120 number from
 121 .In errno.h .
 122 .Sh ERRORS
 123 These functions may fail if:
 124 .Bl -tag -width Er
 125 .\" ==========
 126 .It Bq Er EBADF
 127 The value specified by
 128 .Fa filedes
 129 is negative or would cause the process to exceed the maximum number of
 130 open files it is allowed..
 131 .\" ==========
 132 .It Bq Er EINVAL
 133 The value of
 134 .Fa file_actions
 135 is invalid.
 136 .\" ==========
 137 .It Bq Er ENOMEM
 138 Insufficient memory was available eo add to the
 139 .Fa file_actions .
 140 .El
 141 .Sh SEE ALSO
 142 .Xr posix_spawn 2 ,
 143 .Xr posix_spawnp 2 ,
 144 .Xr posix_spawn_file_actions_init 3 ,
 145 .Xr posix_spawn_file_actions_destroy 3 ,
 146 .Sh STANDARDS
 147 .St -susv3 [SPN]
 148 .Sh HISTORY
 149 The
 150 .Fn posix_spawn_file_actions_init
 151 and
 152 .Fn posix_spawn_file_actions_destroy
 153 function calls appeared in
 154 .St -susv3 [SPN] .