posix_spawnp man page on Solaris

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
Solaris logo
[printable version]

posix_spawn(3C)		 Standard C Library Functions	       posix_spawn(3C)

NAME
       posix_spawn, posix_spawnp - spawn a process

SYNOPSIS
       #include <spawn.h>

       int  posix_spawn(pid_t  *restrict pid, const char *restrict path, const
       posix_spawn_file_actions_t   *file_actions,   const   posix_spawnattr_t
       *restrict    attrp,    char    *const   argv[restrict],	 char	*const
       envp[restrict]);

       int posix_spawnp(pid_t *restrict pid, const char *restrict file,	 const
       posix_spawn_file_actions_t   *file_actions,   const   posix_spawnattr_t
       *restrict   attrp,   char   *const    argv[restrict],	char	*const
       envp[restrict]);

DESCRIPTION
       The  posix_spawn()  and	posix_spawnp()	functions create a new process
       (child process) from the specified process image. The new process image
       is  constructed	from  a regular executable file called the new process
       image file.

       When a C program is executed as the result of this call, it is  entered
       as a C language function call as follows:

       int main(int argc, char *argv[]);

       where  argc  is	the  argument  count and argv is an array of character
       pointers to the arguments themselves. In addition, the following	 vari‐
       able

       extern char **environ;

       is  initialized	as  a pointer to an array of character pointers to the
       environment strings.

       The argument argv is an array of character pointers to  null-terminated
       strings.	 The  last  member  of this array is a null pointer and is not
       counted in argc. These strings constitute the argument  list  available
       to  the new process image. The value in argv[0] should point to a file‐
       name that is associated with the process image  being  started  by  the
       posix_spawn() or posix_spawnp() function.

       The  argument envp is an array of character pointers to null-terminated
       strings. These strings constitute the environment for the  new  process
       image. The environment array is terminated by a null pointer.

       The number of bytes available for the child process's combined argument
       and environment lists is {ARG_MAX}, counting  all  character  pointers,
       the  strings they point to, the trailing null bytes in the strings, and
       the list-terminating null pointers. There is no additional system over‐
       head included in this total.

       The  path  argument  to posix_spawn() is a pathname that identifies the
       new process image file to execute.

       The file parameter to posix_spawnp() is used to	construct  a  pathname
       that  identifies the new process image file. If the file parameter con‐
       tains a slash character, the file parameter is used as the pathname for
       the new process image file. Otherwise, the path prefix for this file is
       obtained by a search of the directories passed as the environment vari‐
       able  PATH. If this environment variable is not defined, the results of
       the search are implementation-defined.

       If file_actions is a null pointer, then file descriptors	 open  in  the
       calling	process	 remain	 open  in  the child process, except for those
       whose close-on-exec flag FD_CLOEXEC is set (see fcntl(2)).   For	 those
       file  descriptors that remain open, all attributes of the corresponding
       open file descriptions, including file  locks  (see  fcntl(2)),	remain
       unchanged.

       If  file_actions	 is  not  NULL,	 then the file descriptors open in the
       child process are those open in the calling process as modified by  the
       spawn file actions object pointed to by file_actions and the FD_CLOEXEC
       flag of each remaining  open  file  descriptor  after  the  spawn  file
       actions	have  been  processed.	The  effective order of processing the
       spawn file actions are:

       1.  The set of open file descriptors for the  child  process  are  ini‐
	   tially  the	same  set  as  is  open	 for  the calling process. All
	   attributes of the corresponding open file  descriptions,  including
	   file locks (see fcntl(2)), remain unchanged.

       2.  The signal mask, signal default actions, and the effective user and
	   group IDs for the child process are changed	as  specified  in  the
	   attributes object referenced by attrp.

       3.  The	file  actions  specified  by the spawn file actions object are
	   performed in the order in which they were added to the  spawn  file
	   actions object.

       4.  Any file descriptor that has its FD_CLOEXEC flag set (see fcntl(2))
	   is closed.

       The posix_spawnattr_t  spawn  attributes	 object	 type  is  defined  in
       <spawn.h>. It contains at least the attributes defined below.

       If  the	POSIX_SPAWN_SETPGROUP flag is set in the spawn-flags attribute
       of the object referenced by attrp, and the  spawn-pgroup	 attribute  of
       the same object is non-zero, then the child's process group is as spec‐
       ified in the spawn-pgroup attribute of the object referenced by attrp.

       As a special case, if the POSIX_SPAWN_SETPGROUP	flag  is  set  in  the
       spawn-flags attribute of the object referenced by attrp, and the spawn-
       pgroup attribute of the same object is set to zero, then the child will
       be  in a new process group with a process group ID equal to its process
       ID.

       If the  POSIX_SPAWN_SETPGROUP  flag  is	not  set  in  the  spawn-flags
       attribute  of  the  object  referenced  by attrp, the new child process
       inherits the parent's process group.

	If the	POSIX_SPAWN_SETSCHEDPARAM  flag	 is  set  in  the  spawn-flags
       attribute  of the object referenced by attrp, but POSIX_SPAWN_SETSCHED‐
       ULER is not set, the new process image  initially  has  the  scheduling
       policy  of the calling process with the scheduling parameters specified
       in the spawn-schedparam attribute of the object referenced by attrp.

       If the POSIX_SPAWN_SETSCHEDULER flag is set in spawn-flags attribute of
       the  object  referenced	by  attrp  (regardless	of  the setting of the
       POSIX_SPAWN_SETSCHEDPARAM flag), the new process	 image	initially  has
       the  scheduling	policy specified in the spawn-schedpolicy attribute of
       the object referenced by attrp and the scheduling parameters  specified
       in the spawn-schedparam attribute of the same object.

       The  POSIX_SPAWN_RESETIDS  flag	in  the	 spawn-flags  attribute of the
       object referenced by attrp governs the effective user ID of  the	 child
       process. If this flag is not set, the child process inherits the parent
       process's effective user ID. If this flag is set, the  child  process's
       effective  user	ID  is	reset  to the parent's real user ID. In either
       case, if the set-user-ID mode bit of the new process image file is set,
       the effective user ID of the child process becomes that file's owner ID
       before the new process image begins execution.  If this	flag  is  set,
       the  child  process's  effective	 user ID is reset to the parent's real
       user ID. In either case, if the set-user-ID mode bit of the new process
       image  file  is set, the effective user ID of the child process becomes
       that file's owner ID before the new process image begins execution.

       The POSIX_SPAWN_RESETIDS flag  in  the  spawn-flags  attribute  of  the
       object  referenced  by attrp also governs the effective group ID of the
       child process. If this flag is not set, the child process inherits  the
       parent  process's  effective  group  ID. If this flag is set, the child
       process's effective group ID is reset to the parent's real group ID. In
       either case, if the set-group-ID mode bit of the new process image file
       is set, the effective group ID of the child process becomes that file's
       group ID before the new process image begins execution.

       If  the POSIX_SPAWN_SETSIGMASK flag is set in the spawn-flags attribute
       of the object referenced by attrp, the child process initially has  the
       signal mask specified in the spawn-sigmask attribute of the object ref‐
       erenced by attrp.

       If the POSIX_SPAWN_SETSIGDEF flag is set in the	spawn-flags  attribute
       of  the object referenced by attrp, the signals specified in the spawn-
       sigdefault attribute of the same object is set to their default actions
       in  the	child process. Signals set to the default action in the parent
       process are set to the default action in the child process.

       Signals set to be caught by the calling process are set to the  default
       action in the child process.

       Except  for  SIGCHLD,  signals set to be ignored by the calling process
       image are set to be ignored by  the  child  process,  unless  otherwise
       specified  by  the  POSIX_SPAWN_SETSIGDEF  flag being set in the spawn-
       flags attribute of the object referenced by attrp and the signals being
       indicated in the spawn-sigdefault attribute of the object referenced by
       attrp.

       If the SIGCHLD signal is set to be ignored by the calling  process,  it
       is  unspecified	whether	 the SIGCHLD signal is set to be ignored or to
       the default action in the child process, unless otherwise specified  by
       the  POSIX_SPAWN_SETSIGDEF  flag being set in the spawn-flags attribute
       of the object referenced by attrp and the SIGCHLD  signal  being	 indi‐
       cated  in  the  spawn-sigdefault	 attribute of the object referenced by
       attrp.

       If the value of the attrp pointer is NULL, then the default values  are
       used.

       All  process  attributes, other than those influenced by the attributes
       set in the object referenced by attrp as specified above or by the file
       descriptor  manipulations  specified  in file_actions appear in the new
       process image as though fork(2) had  been  called  to  create  a	 child
       process	and  then a member of the exec(2) family of functions had been
       called by the child process to execute the new process image.

       The fork handlers are not run when posix_spawn() or  posix_spawnp()  is
       called.

RETURN VALUES
	Upon  successful  completion,  posix_spawn() and posix_spawnp() return
       the process ID of the child process to the parent process in the	 vari‐
       able  pointed  to  by  a	 non-null pid argument, and return zero as the
       function return value. Otherwise, no  child  process  is	 created,  the
       value stored into the variable pointed to by a non-null pid is unspeci‐
       fied, and an error number is returned as the function return  value  to
       indicate	 the error. If the pid argument is a null pointer, the process
       ID of the child is not returned to the caller.

ERRORS
       The posix_spawn() and posix_spawnp() functions will fail if:

       EINVAL	       The  value  specified  by  file_actions	or  attrp   is
		       invalid.

       If  this	 error	occurs	after the calling process successfully returns
       from the posix_spawn() or posix_spawnp() function,  the	child  process
       might exit with exit status 127.

       If  posix_spawn()  or  posix_spawnp() fails for any of the reasons that
       would cause fork() or one of the exec family of functions to  fail,  an
       error  value  is returned as described by fork() and exec, respectively
       (or, if	the  error  occurs  after  the	calling	 process  successfully
       returns, the child process exits with exit status 127).

       If  POSIX_SPAWN_SETPGROUP  is  set  in the spawn-flags attribute of the
       object referenced by attrp, and posix_spawn() or	 posix_spawnp()	 fails
       while changing the child's process group, an error value is returned as
       described by setpgid(2) (or, if the  error  occurs  after  the  calling
       process	successfully returns, the child process exits with exit status
       127).

       If POSIX_SPAWN_SETSCHEDPARAM is set and POSIX_SPAWN_SETSCHEDULER is not
       set  in	the  spawn-flags  attribute of the object referenced by attrp,
       then if posix_spawn() or posix_spawnp() fails for any  of  the  reasons
       that  would  cause  sched_setparam(3RT)	to  fail,  an  error  value is
       returned as described by sched_setparam()  (or,	if  the	 error	occurs
       after the calling process successfully returns, the child process exits
       with exit status 127).

       If POSIX_SPAWN_SETSCHEDULER is set in the spawn-flags attribute of  the
       object  referenced  by  attrp,  and  if posix_spawn() or posix_spawnp()
       fails for any of the reasons that would	cause  sched_setscheduler(3RT)
       to  fail,  an  error  value is returned as described by sched_setsched‐
       uler() (or, if the error occurs after the calling process  successfully
       returns, the child process exits with exit status 127).

       If  the	file_actions  argument is not NULL and specifies any close(2),
       dup2(3C), or open(2) actions to be performed, and if  posix_spawn()  or
       posix_spawnp()  fails  for any of the reasons that would cause close(),
       dup2(), or open() to fail, an error value is returned as	 described  by
       close(),	 dup2(),  and  open(),	respectively  (or, if the error occurs
       after the calling process successfully returns, the child process exits
       with  exit status 127). An open file action might, by itself, result in
       any of the errors described by close() or dup2(), in addition to	 those
       described by open().

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Standard			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │MT-Safe			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       alarm(2),  chmod(2),  close(2),	dup(2),	 exec(2),  exit(2),  fcntl(2),
       fork(2), kill(2), open(2), setpgid(2),  setuid(2),  stat(2),  times(2),
       dup2(3C),			posix_spawn_file_actions_addclose(3C),
       posix_spawn_file_actions_adddup2(3C),
       posix_spawn_file_actions_addopen(3C),
       posix_spawn_file_actions_destroy(3C),
       posix_spawn_file_actions_init(3C),	  posix_spawnattr_destroy(3C),
       posix_spawnattr_init(3C),	    posix_spawnattr_getsigdefault(3C),
       posix_spawnattr_getflags(3C),		posix_spawnattr_getpgroup(3C),
       posix_spawnattr_getschedparam(3C),  posix_spawnattr_getschedpolicy(3C),
       posix_spawnattr_getsigmask(3C),		 posix_spawnattr_setflags(3C),
       posix_spawnattr_setpgroup(3C),	    posix_spawnattr_setschedparam(3C),
       posix_spawnattr_setschedpolicy(3C),  posix_spawnattr_setsigdefault(3C),
       posix_spawnattr_setsigmask(3C),	sched_setparam(3RT),   sched_setsched‐
       uler(3RT), wait(3C), attributes(5), standards(5)

SunOS 5.10			  22 Mar 2004		       posix_spawn(3C)
[top]

List of man pages available for Solaris

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net