lib/libc/gen/posix_spawn_file_actions_addopen.3

   1 .\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" Portions of this text are reprinted and reproduced in electronic form
  26 .\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
  27 .\" Portable Operating System Interface (POSIX), The Open Group Base
  28 .\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
  29 .\" Electrical and Electronics Engineers, Inc and The Open Group.  In the
  30 .\" event of any discrepancy between this version and the original IEEE and
  31 .\" The Open Group Standard, the original IEEE and The Open Group Standard is
  32 .\" the referee document.  The original Standard can be obtained online at
  33 .\"     http://www.opengroup.org/unix/online.html.
  34 .\"
  35 .\" $FreeBSD: src/lib/libc/gen/posix_spawn_file_actions_addopen.3,v 1.2 2008/07/28 09:36:56 ed Exp $
  36 .\"
  37 .Dd April 7, 2009
  38 .Dt POSIX_SPAWN_FILE_ACTIONS_ADDOPEN 3
  39 .Os
  40 .Sh NAME
  41 .Nm posix_spawn_file_actions_addopen ,
  42 .Nm posix_spawn_file_actions_adddup2 ,
  43 .Nm posix_spawn_file_actions_addclose
  44 .Nd "add open, dup2 or close action to spawn file actions object"
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In spawn.h
  49 .Ft int
  50 .Fn posix_spawn_file_actions_addopen "posix_spawn_file_actions_t * file_actions" "int fildes" "const char *restrict path" "int oflag" "mode_t mode"
  51 .Ft int
  52 .Fn posix_spawn_file_actions_adddup2 "posix_spawn_file_actions_t * file_actions" "int fildes" "int newfildes"
  53 .Ft int
  54 .Fn posix_spawn_file_actions_addclose "posix_spawn_file_actions_t * file_actions" "int fildes"
  55 .Sh DESCRIPTION
  56 These functions add an open, dup2 or close action to a spawn
  57 file actions object.
  58 .Pp
  59 A spawn file actions object is of type
  60 .Vt posix_spawn_file_actions_t
  61 (defined in
  62 .In spawn.h )
  63 and is used to specify a series of actions to be performed by a
  64 .Fn posix_spawn
  65 or
  66 .Fn posix_spawnp
  67 operation in order to arrive at the set of open file descriptors for the
  68 child process given the set of open file descriptors of the parent.
  69 .Pp
  70 A spawn file actions object, when passed to
  71 .Fn posix_spawn
  72 or
  73 .Fn posix_spawnp ,
  74 specify how the set of open file descriptors in the calling
  75 process is transformed into a set of potentially open file descriptors
  76 for the spawned process.
  77 This transformation is as if the specified sequence of actions was
  78 performed exactly once, in the context of the spawned process (prior to
  79 execution of the new process image), in the order in which the actions
  80 were added to the object; additionally, when the new process image is
  81 executed, any file descriptor (from this new set) which has its
  82 .Dv FD_CLOEXEC
  83 flag set is closed (see
  84 .Fn posix_spawn ) .
  85 .Pp
  86 The
  87 .Fn posix_spawn_file_actions_addopen
  88 function adds an open action to the object referenced by
  89 .Fa file_actions
  90 that causes the file named by
  91 .Fa path
  92 to be opened (as if
  93 .Bd -literal -offset indent
  94 open(path, oflag, mode)
  95 .Ed
  96 .Pp
  97 had been called, and the returned file descriptor, if not
  98 .Fa fildes ,
  99 had been changed to
 100 .Fa fildes )
 101 when a new process is spawned using this file actions object.
 102 If
 103 .Fa fildes
 104 was already an open file descriptor, it is closed before the new
 105 file is opened.
 106 .Pp
 107 The string described by
 108 .Fa path
 109 is copied by the
 110 .Fn posix_spawn_file_actions_addopen
 111 function.
 112 .Pp
 113 The
 114 .Fn posix_spawn_file_actions_adddup2
 115 function adds a dup2 action to the object referenced by
 116 .Fa file_actions
 117 that causes the file descriptor
 118 .Fa fildes
 119 to be duplicated as
 120 .Fa newfildes
 121 (as if
 122 .Bd -literal -offset indent
 123 dup2(fildes, newfildes)
 124 .Ed
 125 .Pp
 126 had been called) when a new process is spawned using this file actions object.
 127 .Pp
 128 The
 129 .Fn posix_spawn_file_actions_addclose
 130 function adds a close action to the object referenced by
 131 .Fa file_actions
 132 that causes the file descriptor
 133 .Fa fildes
 134 to be closed (as if
 135 .Bd -literal -offset indent
 136 close(fildes)
 137 .Ed
 138 .Pp
 139 had been called) when a new process is spawned using this file actions
 140 object.
 141 .Sh RETURN VALUES
 142 Upon successful completion, these functions return zero;
 143 otherwise, an error number is returned to indicate the error.
 144 .Sh ERRORS
 145 These
 146 functions fail if:
 147 .Bl -tag -width Er
 148 .It Bq Er EINVAL
 149 The value specified by
 150 .Fa fildes
 151 or
 152 .Fa newfildes
 153 is negative.
 154 .It Bq Er ENOMEM
 155 Insufficient memory exists to add to the spawn file actions object.
 156 .El
 157 .Sh SEE ALSO
 158 .Xr close 2 ,
 159 .Xr dup2 2 ,
 160 .Xr open 2 ,
 161 .Xr posix_spawn 3 ,
 162 .Xr posix_spawn_file_actions_destroy 3 ,
 163 .Xr posix_spawn_file_actions_init 3 ,
 164 .Xr posix_spawnp 3
 165 .Sh STANDARDS
 166 The
 167 .Fn posix_spawn_file_actions_addopen ,
 168 .Fn posix_spawn_file_actions_adddup2
 169 and
 170 .Fn posix_spawn_file_actions_addclose
 171 functions conform to
 172 .St -p1003.1-2001 .
 173 .Sh HISTORY
 174 The
 175 .Fn posix_spawn_file_actions_addopen ,
 176 .Fn posix_spawn_file_actions_adddup2
 177 and
 178 .Fn posix_spawn_file_actions_addclose
 179 functions first appeared in
 180 .Fx 8.0 .
 181 .Sh AUTHORS
 182 .An Ed Schouten Aq ed@FreeBSD.org