POSIX_SPAWN_FILE_ACTIONS_ADDPCOLSOISXE(P3r)ogrammerP'OsSIMXa_nSuPaAlWN_FILE_ACTIONS_ADDCLOSE(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       posix_spawn_file_actions_addclose, posix_spawn_file_actions_addopen --
       add close or open action to spawn file actions object (AADDVVAANNCCEEDD
       RREEAALLTTIIMMEE)

SSYYNNOOPPSSIISS
       #include <spawn.h>

       int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t
           *_f_i_l_e___a_c_t_i_o_n_s, int _f_i_l_d_e_s);
       int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t
           *restrict _f_i_l_e___a_c_t_i_o_n_s, int _f_i_l_d_e_s,
           const char *restrict _p_a_t_h, int _o_f_l_a_g, mode_t _m_o_d_e);

DDEESSCCRRIIPPTTIIOONN
       These functions shall add or delete a close or open action to a spawn
       file actions object.

       A spawn file actions object is of type ppoossiixx__ssppaawwnn__ffiillee__aaccttiioonnss__tt
       (defined in _<_s_p_a_w_n_._h_>) and is used to specify a series of actions to be
       performed by a _p_o_s_i_x___s_p_a_w_n() or _p_o_s_i_x___s_p_a_w_n_p() operation in order to
       arrive at the set of open file descriptors for the child process given
       the set of open file descriptors of the parent.  POSIX.1-2008 does not
       define comparison or assignment operators for the type
       ppoossiixx__ssppaawwnn__ffiillee__aaccttiioonnss__tt.

       A spawn file actions object, when passed to _p_o_s_i_x___s_p_a_w_n() or
       _p_o_s_i_x___s_p_a_w_n_p(), shall specify how the set of open file descriptors in
       the calling process is transformed into a set of potentially open file
       descriptors for the spawned process. This transformation shall be as if
       the specified sequence of actions was performed exactly once, in the
       context of the spawned process (prior to execution of the new process
       image), in the order in which the actions were added to the object;
       additionally, when the new process image is executed, any file
       descriptor (from this new set) which has its FD_CLOEXEC flag set shall
       be closed (see _p_o_s_i_x___s_p_a_w_n()).

       The _p_o_s_i_x___s_p_a_w_n___f_i_l_e___a_c_t_i_o_n_s___a_d_d_c_l_o_s_e() function shall add a _c_l_o_s_e
       action to the object referenced by _f_i_l_e___a_c_t_i_o_n_s that shall cause the
       file descriptor _f_i_l_d_e_s to be closed (as if _c_l_o_s_e(_f_i_l_d_e_s) had been
       called) when a new process is spawned using this file actions object.

       The _p_o_s_i_x___s_p_a_w_n___f_i_l_e___a_c_t_i_o_n_s___a_d_d_o_p_e_n() function shall add an _o_p_e_n
       action to the object referenced by _f_i_l_e___a_c_t_i_o_n_s that shall cause the
       file named by _p_a_t_h to be opened (as if _o_p_e_n(_p_a_t_h, _o_f_l_a_g, _m_o_d_e) had been
       called, and the returned file descriptor, if not _f_i_l_d_e_s, had been
       changed to _f_i_l_d_e_s) when a new process is spawned using this file
       actions object. If _f_i_l_d_e_s was already an open file descriptor, it shall
       be closed before the new file is opened.

       The string described by _p_a_t_h shall be copied by the
       _p_o_s_i_x___s_p_a_w_n___f_i_l_e___a_c_t_i_o_n_s___a_d_d_o_p_e_n() function.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, these functions shall return zero;
       otherwise, an error number shall be returned to indicate the error.

EERRRROORRSS
       The _p_o_s_i_x___s_p_a_w_n___f_i_l_e___a_c_t_i_o_n_s___a_d_d_o_p_e_n() function shall fail if:

       EEBBAADDFF  The value specified by _f_i_l_d_e_s is negative or greater than or
              equal to {OPEN_MAX}.

       The _p_o_s_i_x___s_p_a_w_n___f_i_l_e___a_c_t_i_o_n_s___a_d_d_c_l_o_s_e() function shall fail if:

       EEBBAADDFF  The value specified by _f_i_l_d_e_s is negative.

       These functions may fail if:

       EEIINNVVAALL The value specified by _f_i_l_e___a_c_t_i_o_n_s is invalid.

       EENNOOMMEEMM Insufficient memory exists to add to the spawn file actions
              object.

       It shall not be considered an error for the _f_i_l_d_e_s argument passed to
       these functions to specify a file descriptor for which the specified
       operation could not be performed at the time of the call. Any such
       error will be detected when the associated file actions object is later
       used during a _p_o_s_i_x___s_p_a_w_n() or _p_o_s_i_x___s_p_a_w_n_p() operation.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       These functions are part of the Spawn option and need not be provided
       on all implementations.

       Implementations may use file descriptors that must be inherited into
       child processes for the child process to remain conforming, such as for
       message catalog or tracing purposes. Therefore, an application that
       calls _p_o_s_i_x___s_p_a_w_n___f_i_l_e___a_c_t_i_o_n_s___a_d_d_c_l_o_s_e() with an arbitrary integer
       risks non-conforming behavior, and this function can only portably be
       used to close file descriptor values that the application has obtained
       through explicit actions, or for the three file descriptors
       corresponding to the standard file streams. In order to avoid a race
       condition of leaking an unintended file descriptor into a child
       process, an application should consider opening all file descriptors
       with the FD_CLOEXEC bit set unless the file descriptor is intended to
       be inherited across _e_x_e_c.

RRAATTIIOONNAALLEE
       A spawn file actions object may be initialized to contain an ordered
       sequence of _c_l_o_s_e(), _d_u_p_2(), and _o_p_e_n() operations to be used by
       _p_o_s_i_x___s_p_a_w_n() or _p_o_s_i_x___s_p_a_w_n_p() to arrive at the set of open file
       descriptors inherited by the spawned process from the set of open file
       descriptors in the parent at the time of the _p_o_s_i_x___s_p_a_w_n() or
       _p_o_s_i_x___s_p_a_w_n_p() call. It had been suggested that the _c_l_o_s_e() and _d_u_p_2()
       operations alone are sufficient to rearrange file descriptors, and that
       files which need to be opened for use by the spawned process can be
       handled either by having the calling process open them before the
       _p_o_s_i_x___s_p_a_w_n() or _p_o_s_i_x___s_p_a_w_n_p() call (and close them after), or by
       passing pathnames to the spawned process (in _a_r_g_v) so that it may open
       them itself. The standard developers recommend that applications use
       one of these two methods when practical, since detailed error status on
       a failed open operation is always available to the application this
       way. However, the standard developers feel that allowing a spawn file
       actions object to specify open operations is still appropriate because:

        1. It is consistent with equivalent POSIX.5 (Ada) functionality.

        2. It supports the I/O redirection paradigm commonly employed by POSIX
           programs designed to be invoked from a shell. When such a program
           is the child process, it may not be designed to open files on its
           own.

        3. It allows file opens that might otherwise fail or violate file
           ownership/access rights if executed by the parent process.

       Regarding 2. above, note that the spawn open file action provides to
       _p_o_s_i_x___s_p_a_w_n() and _p_o_s_i_x___s_p_a_w_n_p() the same capability that the shell
       redirection operators provide to _s_y_s_t_e_m(), only without the intervening
       execution of a shell; for example:

           ssyysstteemm ((""mmyypprroogg <<ffiillee11 33<<ffiillee22""));;

       Regarding 3. above, note that if the calling process needs to open one
       or more files for access by the spawned process, but has insufficient
       spare file descriptors, then the open action is necessary to allow the
       _o_p_e_n() to occur in the context of the child process after other file
       descriptors have been closed (that must remain open in the parent).

       Additionally, if a parent is executed from a file having a ``set-user-
       id'' mode bit set and the POSIX_SPAWN_RESETIDS flag is set in the spawn
       attributes, a file created within the parent process will (possibly
       incorrectly) have the parent's effective user ID as its owner, whereas
       a file created via an _o_p_e_n() action during _p_o_s_i_x___s_p_a_w_n() or
       _p_o_s_i_x___s_p_a_w_n_p() will have the parent's real ID as its owner; and an open
       by the parent process may successfully open a file to which the real
       user should not have access or fail to open a file to which the real
       user should have access.

   FFiillee DDeessccrriippttoorr MMaappppiinngg
       The standard developers had originally proposed using an array which
       specified the mapping of child file descriptors back to those of the
       parent. It was pointed out by the ballot group that it is not possible
       to reshuffle file descriptors arbitrarily in a library implementation
       of _p_o_s_i_x___s_p_a_w_n() or _p_o_s_i_x___s_p_a_w_n_p() without provision for one or more
       spare file descriptor entries (which simply may not be available). Such
       an array requires that an implementation develop a complex strategy to
       achieve the desired mapping without inadvertently closing the wrong
       file descriptor at the wrong time.

       It was noted by a member of the Ada Language Bindings working group
       that the approved Ada Language _S_t_a_r_t___P_r_o_c_e_s_s family of POSIX process
       primitives use a caller-specified set of file actions to alter the
       normal _f_o_r_k()/_e_x_e_c semantics for inheritance of file descriptors in a
       very flexible way, yet no such problems exist because the burden of
       determining how to achieve the final file descriptor mapping is
       completely on the application. Furthermore, although the file actions
       interface appears frightening at first glance, it is actually quite
       simple to implement in either a library or the kernel.

       The _p_o_s_i_x___s_p_a_w_n___f_i_l_e___a_c_t_i_o_n_s___a_d_d_c_l_o_s_e() function is not required to
       check whether the file descriptor is less than {OPEN_MAX} because on
       some implementations {OPEN_MAX} reflects the RLIMIT_NOFILE soft limit
       and therefore calling _s_e_t_r_l_i_m_i_t() to reduce this limit can result in an
       {OPEN_MAX} value less than or equal to an already open file descriptor.
       Applications need to be able to close such file descriptors on spawn.
       On implementations where {OPEN_MAX} does not change, it is recommended
       that _p_o_s_i_x___s_p_a_w_n___f_i_l_e___a_c_t_i_o_n_s___a_d_d_c_l_o_s_e() should return [[EEBBAADDFF]] if
       _f_i_l_d_e_s is greater than or equal to {OPEN_MAX}.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _c_l_o_s_e(), _d_u_p(), _o_p_e_n(), _p_o_s_i_x___s_p_a_w_n(),
       _p_o_s_i_x___s_p_a_w_n___f_i_l_e___a_c_t_i_o_n_s___a_d_d_d_u_p_2(), _p_o_s_i_x___s_p_a_w_n___f_i_l_e___a_c_t_i_o_n_s___d_e_s_t_r_o_y()

       The Base Definitions volume of POSIX.1-2008, <<ssppaawwnn..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be obtained online
       at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013 POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE(3)
