👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for posix_spawn_file_actions_addclose (linux section 3posix)

POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE(P)POSIX Programmer's ManualPOSIX_SPAWN_FILE_ACTIONS_ADDCLOSE(P)

NAME
       posix_spawn_file_actions_addclose,  posix_spawn_file_actions_addopen  -	add close or open
       action to spawn file actions object (ADVANCED REALTIME)

SYNOPSIS
       #include <spawn.h>

       int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t *
	      file_actions, int fildes);
       int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t *
	      restrict file_actions, int fildes,
	      const char *restrict path, int oflag, mode_t mode);

DESCRIPTION
       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 posix_spawn_file_actions_t (defined  in  <spawn.h>)
       and  is	used  to  specify  a  series  of  actions  to  be performed by a posix_spawn() or
       posix_spawnp() 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. IEEE Std 1003.1-2001
       does    not    define	comparison    or    assignment	  operators    for    the    type
       posix_spawn_file_actions_t.

       A spawn file actions object, when passed to posix_spawn() or posix_spawnp(), 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 posix_spawn() ).

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

       The  posix_spawn_file_actions_addopen()	function  shall  add an open action to the object
       referenced by file_actions that shall cause the file named by path to  be  opened  (as  if
       open( path, oflag, mode) had been called, and the returned file descriptor, if not fildes,
       had been changed to fildes) when a new process is spawned using this file actions  object.
       If  fildes  was already an open file descriptor, it shall be closed before the new file is
       opened.

       The string described by path shall be  copied  by  the  posix_spawn_file_actions_addopen()
       function.

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

ERRORS
       These functions shall fail if:

       EBADF  The value specified by fildes is negative or greater than or equal to {OPEN_MAX}.

       These functions may fail if:

       EINVAL The value specified by file_actions is invalid.

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

       It shall not be considered an error for the fildes 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 posix_spawn() or posix_spawnp() operation.

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       These  functions  are part of the Spawn option and need not be provided on all implementa-
       tions.

RATIONALE
       A spawn file actions object may be initialized to contain an ordered sequence of  close(),
       dup2(),	and  open() operations to be used by posix_spawn() or posix_spawnp() 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 posix_spawn() or posix_spawnp() call.
       It had been suggested that the close() and dup2() operations alone are sufficient to rear-
       range  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
       posix_spawn()  or  posix_spawnp()  call (and close them after), or by passing filenames to
       the spawned process (in argv) 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 posix_spawn() and
       posix_spawnp() the same capability that the shell redirection operators	provide  to  sys-
       tem(), only without the intervening execution of a shell; for example:

	      system ("myprog <file1 3<file2");

       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 open() 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 open() action during posix_spawn() or posix_spawnp()
       will have the parent's real ID as its owner; and an open by the parent  process	may  suc-
       cessfully 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.

   File Descriptor Mapping
       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 posix_spawn() or posix_spawnp() 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 inad-
       vertently 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  Start_Process	family	of POSIX process primitives use a caller-specified set of
       file actions to alter the normal fork()/ exec semantics for inheritance of  file  descrip-
       tors  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.  Fur-
       thermore,  although  the file actions interface appears frightening at first glance, it is
       actually quite simple to implement in either a library or the kernel.

FUTURE DIRECTIONS
       None.

SEE ALSO
       close()	,  dup()  ,  open()  ,	posix_spawn()  ,   posix_spawn_file_actions_adddup2()	,
       posix_spawn_file_actions_destroy()  ,  posix_spawnp()  ,  the  Base  Definitions volume of
       IEEE Std 1003.1-2001, <spawn.h>

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003	     POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE(P)


All times are GMT -4. The time now is 09:07 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password





Not a Forum Member?
Forgot Password?