Movatterモバイル変換

#include <spawn.h>intposix_spawn(pid_t *restrictpid,const char *restrictpath,const posix_spawn_file_actions_t *file_actions,const posix_spawnattr_t *restrictattrp,char *constargv[restrict],char *constenvp[restrict]);

intposix_spawnp(pid_t *restrictpid,const char *restrictfile,const posix_spawn_file_actions_t *file_actions,const posix_spawnattr_t *restrictattrp,char *constargv[restrict],char *constenvp[restrict]);

Description

Theposix_spawn() andposix_spawnp() functions create a new process (child process) fromthe specified process image. The new process image is constructed from aregular 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(intargc, char *argv[]);

whereargc is the argument count andargv is an array ofcharacter pointers to the arguments themselves. In addition, the following variable

extern char **environ;

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

The argumentargv is an array of character pointers to null-terminated strings.The last member of this array is a null pointer and isnot counted inargc. These strings constitute the argument list available tothe new process image. The value inargv[0] should point to a filenamethat is associated with the process image being started by theposix_spawn()orposix_spawnp() function.

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

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

Thepath argument toposix_spawn() is a pathname that identifies the newprocess image file to execute.

Thefile parameter toposix_spawnp() is used to construct a pathname thatidentifies the new process image file. If the file parameter contains aslash character, the file parameter is used as the pathname for thenew process image file. Otherwise, the path prefix for this file is obtainedby a search of the directories passed as the environment variablePATH.If this environment variable is not defined, the results of the searchare implementation-defined.

Iffile_actions is a null pointer, then file descriptors open in thecalling process remain open in the child process, except for those whoseclose-on-exec flagFD_CLOEXEC is set (seefcntl(2)). For those file descriptorsthat remain open, all attributes of the corresponding open file descriptions, includingfile locks (seefcntl(2)), remain unchanged.

Iffile_actions is notNULL, then the file descriptors open in thechild process are those open in the calling process as modified bythe spawn file actions object pointed to byfile_actions and theFD_CLOEXECflag of each remaining open file descriptor after the spawn file actionshave been processed. The effective order of processing the spawn file actionsare:

The set of open file descriptors for the child process are initially the same set as is open for the calling process. All attributes of the corresponding open file descriptions, including file locks (seefcntl(2)), remain unchanged.
The signal mask, signal default or ignore actions, and the effective user and group IDs for the child process are changed as specified in the attributes object referenced byattrp.
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.
Any file descriptor that has itsFD_CLOEXEC flag set (seefcntl(2)) is closed.

Theposix_spawnattr_t spawn attributes object type is defined in <spawn.h>. It containsat least the attributes defined below.

If thePOSIX_SPAWN_SETPGROUP flag is set in thespawn-flags attribute of theobject referenced byattrp, and thespawn-pgroup attribute of the same objectis non-zero, then the child's process group is as specified in thespawn-pgroupattribute of the object referenced byattrp.

As a special case, if thePOSIX_SPAWN_SETPGROUP flag is set in thespawn-flags attribute of the object referenced byattrp, and thespawn-pgroup attributeof the same object is set to zero, then the child will bein a new process group with a process group ID equal toits process ID.

If thePOSIX_SPAWN_SETPGROUP flag is not set in thespawn-flags attribute ofthe object referenced byattrp, the new child process inherits the parent'sprocess group.

If thePOSIX_SPAWN_SETSCHEDPARAM flag is set in thespawn-flags attribute of theobject referenced byattrp, butPOSIX_SPAWN_SETSCHEDULER is not set, the new processimage initially has the scheduling policy of the calling process with the schedulingparameters specified in thespawn-schedparam attribute of the object referenced byattrp.

If thePOSIX_SPAWN_SETSCHEDULER flag is set inspawn-flags attribute of the objectreferenced byattrp (regardless of the setting of thePOSIX_SPAWN_SETSCHEDPARAM flag), thenew process image initially has the scheduling policy specified in thespawn-schedpolicy attributeof the object referenced byattrp and the scheduling parameters specified inthespawn-schedparam attribute of the same object.

ThePOSIX_SPAWN_RESETIDS flag in thespawn-flags attribute of the object referenced byattrp governs the effective user ID of the child process. If thisflag is not set, the child process inherits the parent process's effective userID. If this flag is set, the child process's effective user IDis reset to the parent's real user ID. In either case, ifthe 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 ownerID 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 realuser ID. In either case, if the set-user-ID mode bit of thenew process image file is set, the effective user ID of thechild process becomes that file's owner ID before the new process imagebegins execution.

ThePOSIX_SPAWN_RESETIDS flag in thespawn-flags attribute of the object referenced byattrp also governs the effective group ID of the child process. Ifthis flag is not set, the child process inherits the parent process's effectivegroup ID. If this flag is set, the child process's effective groupID 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 isset, the effective group ID of the child process becomes that file'sgroup ID before the new process image begins execution.

If thePOSIX_SPAWN_SETSIGMASK flag is set in thespawn-flags attribute of theobject referenced byattrp, the child process initially has the signal maskspecified in thespawn-sigmask attribute of the object referenced byattrp.

If thePOSIX_SPAWN_SETSIGDEF flag is set in thespawn-flags attribute of theobject referenced byattrp, the signals specified in thespawn-sigdefault attribute ofthe same object is set to their default actions in the child process.

If thePOSIX_SPAWN_SETSIGIGN_NP flag is set in the spawn-flags attribute of theobject referenced byattrp, the signals specified in thespawn-sigignore attribute ofthe same object are set to be ignored in the child process.

If bothPOSIX_SPAWN_SETSIGDEF andPOSIX_SPAWN_SETSIGIGN_NP flags are set in the spawn-flags attributeof the object referenced byattrp, the actions forPOSIX_SPAWN_SETSIGDEF take precedenceover the actions forPOSIX_SPAWN_SETSIGIGN_NP.

If thePOSIX_SPAWN_NOSIGCHLD_NP flag is set in thespawn-flags attribute of theobject referenced byattrp, noSIGCHLD signal will be posted to theparent process when the child process terminates, regardless of the disposition of theSIGCHLD signal in the parent.SIGCHLD signals are still possible forjob control stop and continue actions if the parent has requested them.

If thePOSIX_SPAWN_WAITPID_NP flag is set in thespawn-flags attribute of theobject referenced byattrp, no wait-for-multiple-pids operation by the parent, as inwait(),waitid(P_ALL), orwaitid(P_PGID), will succeed in reaping the child, and thechild will not be reaped automatically due the disposition of theSIGCHLDsignal being set to be ignored in the parent. Only aspecific wait for the child, as inwaitid(P_PID,pid), is allowed andit is required, else when the child exits it will remain azombie until the parent exits.

If thePOSIX_SPAWN_NOEXECERR_NP flag is set in the spawn-flags attribute of theobject referenced byattrp, and if the specified process image file cannotbe executed, then theposix_spawn() andposix_spawnp() functions do not fail with oneof theexec(2) error codes, as is normal, but rather return successfullyhaving created a child process that exits immediately with exit status 127. Thisflag permitssystem(3C) andpopen(3C) to be implemented withposix_spawn() and stillconform strictly to their POSIX specifications.

Signals set to be caught or set to the default action inthe calling process are set to the default action in the childprocess, unless thePOSIX_SPAWN_SETSIGIGN_NP flag is set in the spawn-flags attribute ofthe object referenced byattrp and the signals are specified in thespawn-sigignoreattribute of the same object.

Except forSIGCHLD, signals set to be ignored by the calling processimage are set to be ignored by the child process, unless otherwisespecified by thePOSIX_SPAWN_SETSIGDEF flag being set in thespawn-flags attribute ofthe object referenced byattrp and the signals being indicated in thespawn-sigdefaultattribute of the object referenced byattrp.

If theSIGCHLD signal is set to be ignored by the callingprocess, it is unspecified whether theSIGCHLD signal is set to beignored or to the default action in the child process, unless otherwisespecified by thePOSIX_SPAWN_SETSIGDEF flag being set in thespawn-flags attribute of theobject referenced byattrp and theSIGCHLD signal being indicated in thespawn-sigdefault attribute of the object referenced byattrp.

If the value of theattrp pointer isNULL, then the defaultvalues are used.

All process attributes, other than those influenced by the attributes set inthe object referenced byattrp as specified above or by the filedescriptor manipulations specified infile_actions appear in the new process image asthoughfork() had been called to create a child process and thena member of theexec family of functions had been called bythe child process to execute the new process image.

The fork handlers are not run whenposix_spawn() orposix_spawnp() is called.

Return Values

Upon successful completion,posix_spawn() andposix_spawnp() return the process ID of thechild process to the parent process in the variable pointed to bya non-nullpid argument, and return zero as the function return value. Otherwise,no child process is created, the value stored into the variable pointedto by a non-nullpid is unspecified, and an error number isreturned as the function return value to indicate the error. If thepid argument is a null pointer, the process ID of the child isnot returned to the caller.

Errors

Theposix_spawn() andposix_spawnp() functions will fail if:

EINVAL: The value specified byfile_actions orattrp is invalid.

Ifposix_spawn() orposix_spawnp() fails for any of the reasons that wouldcausefork() or one of theexec family of functions to fail,an error value is returned as described byfork(2) andexec(2), respectively

IfPOSIX_SPAWN_SETPGROUP is set in thespawn-flags attribute of the object referencedbyattrp, andposix_spawn() orposix_spawnp() fails while changing the child's processgroup, an error value is returned as described bysetpgid(2).

IfPOSIX_SPAWN_SETSCHEDPARAM is set andPOSIX_SPAWN_SETSCHEDULER is not set in thespawn-flagsattribute of the object referenced byattrp, then ifposix_spawn() orposix_spawnp()fails for any of the reasons that would causesched_setparam() to fail, anerror value is returned as described bysched_setparam(3C).

IfPOSIX_SPAWN_SETSCHEDULER is set in thespawn-flags attribute of the object referencedbyattrp, and ifposix_spawn() orposix_spawnp() fails for any of thereasons that would causesched_setscheduler() to fail, an error value is returnedas described bysched_setscheduler(3C).

If thefile_actions argument is notNULL and specifies anyclose(),dup2(),oropen() actions to be performed, and ifposix_spawn() orposix_spawnp() fails forany of the reasons that would causeclose(),dup2(), oropen() tofail, an error value is returned as described byclose(2),dup2(3C), oropen(2), respectively. An open file action might, by itself, result in anyof the errors described byclose() ordup2(), in addition to thosedescribed byopen().

If aclose(2) operation is specified to be performed for a filedescriptor that is not open at the time of the call toposix_spawn() orposix_spawnp(), the action does not causeposix_spawn() orposix_spawnp() tofail.

Attributes

Seeattributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Committed
MT-Level	MT-Safe
Standard	See`standards`(5).

Notes

The SUSv3 POSIX standard (The Open Group Base Specifications Issue 6, IEEEStd 1003.1-2001) permits theposix_spawn() andposix_spawnp() functions to return successfully beforesome of the above-described errors are detected, allowing the child process to failinstead:

... if the error occurs after the calling processsuccessfully returns, the child process exits withexit status 127.

With the one exception of when thePOSIX_SPAWN_NOEXECERR_NP flag is passed inthe attributes structure, this behavior is not present in the Solaris implementation.Any error that occurs before the new process image is successfully constructedcauses theposix_spawn() andposix_spawnp() functions to return the corresponding non-zero errorvalue without creating a child process.

ThePOSIX_SPAWN_NOSIGCHLD_NP,POSIX_SPAWN_WAITPID_NP,POSIX_SPAWN_NOEXECERR_NP, andPOSIX_SPAWN_SETSIGIGN_NP flags and theposix_spawnattr_getsigignore_np() andposix_spawnattr_setsigignore_np()functions are non-portable Solaris extensions to theposix_spawn() andposix_spawnp() interfaces.

Skip Navigation Links
Exit Print View
	man pages section 3: Basic Library Functions Oracle Solaris 11 Information Library

Movatterモバイル変換

posix_spawn

, posix_spawnp

Synopsis

Description

Return Values

Errors

Attributes

See Also

Notes