{{Short description|Function that loads and executes a new child process}} {{For|creating characters in a video game|Spawning (video games)}}
'''Spawn''' in computing refers to a function that loads and executes a new child process. The current process may wait for the child to terminate or may continue to execute concurrent computing. Creating a new subprocess requires enough memory in which both the child process and the current program can execute.
There is a family of spawn functions in DOS, inherited by Microsoft Windows.
There is also a different family of spawn functions in an optional extension of the POSIX standards.<ref name="Posix spawn.h">[http://www.opengroup.org/onlinepubs/9699919799/basedefs/spawn.h.html Posix.1-2008 spawn.h]</ref>
==DOS/Windows spawn functions==
The DOS/Windows spawn functions are inspired by Unix functions <code>fork</code> and <code>exec</code>; however, as these operating systems do not support fork,{{efn|Windows Subsystem for Linux implements fork. Other POSIX environments such as Cygwin may have an implementation, but using it is not recommended due to the differences in the process model between POSIX and Windows. Fork is not part of the Windows API and most Windows programs do not use these environments, so do not have access to fork.}} the spawn function was supplied as a replacement for the fork-exec combination. However, the spawn function, although it deals adequately with the most common use cases, lacks the full power of fork-exec, since after fork any process settings which will survive an exec may be changed. However, in most cases, this deficiency can be made up for by using the more low-level {{code|CreateProcess}} API.
In the {{code|spawnl}}, {{code|spawnlp}}, {{code|spawnv}}, and {{code|spawnvp}} calls, the child process inherits the environment of the parent. Files that are open when a {{code|spawn}} call is made remain open in the child process.
===Prototype=== :<syntaxhighlight lang="c" inline>int spawnl(int mode, char* path, char* arg0, ...);</syntaxhighlight> :<syntaxhighlight lang="c" inline>int spawnle(int mode, char* path, char* arg0, ..., char* envp[]);</syntaxhighlight> :<syntaxhighlight lang="c" inline>int spawnlp(int mode, char* path, char* arg0, ...);</syntaxhighlight> :<syntaxhighlight lang="c" inline>int spawnlpe(int mode, char* path, char* arg0, ..., char* envp[]);</syntaxhighlight> :<syntaxhighlight lang="c" inline>int spawnv(int mode, char* path, char* argv[]);</syntaxhighlight> :<syntaxhighlight lang="c" inline>int spawnve(int mode, char* path, char* argv[], char* envp[]);</syntaxhighlight> :<syntaxhighlight lang="c" inline>int spawnvp(int mode, char* path, char* argv[]);</syntaxhighlight> :<syntaxhighlight lang="c" inline>int spawnvpe(int mode, char* path, char* argv[], char* envp[]);</syntaxhighlight>
====Function names==== The base name of each function is {{mono|spawn}}, followed by one or more letters: {| class="wikitable" |- ! Letter||Notes |- | {{Mono|l}} || Command-line arguments are passed individually to the function. |- | {{Mono|v}} || Command-line arguments are passed to the function as an array of pointers. |- | {{Mono|p}} || Uses the PATH argument variable to find the file to be executed. |- | {{Mono|e}} || An array of pointers to environment arguments is explicitly passed to the child process. |- |}
====Mode==== The {{code|mode}} argument determines the way the child is run. Values for {{code|mode}} are:
{| class="wikitable" |- ! Name || Notes |- | {{code|P_OVERLAY}} || Overlays parent process with child, which destroys the parent. This has the same effect as the {{mono|exec*}} functions. |- | {{code|P_WAIT}} || Suspends parent process until the child process has finished executing (synchronous spawn). |- | {{code|P_NOWAIT}}, {{code|P_NOWAITO}} || Continues to execute calling process concurrently with new process (asynchronous spawn). |- | {{code|P_DETACH}} || The child is run in background without access to the console or keyboard. Calls to {{code|_cwait}} upon the new process will fail (asynchronous spawn) |- |}
====Path==== The {{code|path}} argument specifies the filename of the program to execute. For {{code|spawnlp}} and {{code|spawnvp}} only, if the filename does not have a path and is not in the current directory, the PATH environment variable determines which directories to search for the file. The string pointed to by {{code|argv[0]}} is the name of the program to run.
The command line passed to the spawned program is made up of the character strings, {{code|arg0}} through {{code|argn}}, in the {{code|spawn}} call. The accepted maximum combined length of these strings differs between compilers, ranging from 128 characters on Digital Mars<ref name="mars process.h">[http://www.digitalmars.com/rtl/process.html Digital Mars process.h]</ref> to 1024 on Microsoft Visual C++<ref name="msdn">[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vccore98/HTML/_crt_system.2c_._wsystem.asp Microsoft MSDN]</ref> or as much as memory permits, on DJGPP.<ref name="djgpp spawn">[http://www.delorie.com/djgpp/doc/libc/libc_736.html DJGPP spawn*]</ref> The last argument after {{code|argn}} has to be a null pointer.
====argv==== The {{code|argv}} argument is an array of character pointers. The last pointer in the array must be null to indicate the end of the list.
====envp==== The {{code|spawnle}}, {{code|spawnlpe}}, {{code|spawnve}}, and {{code|spawnvpe}} calls allow the user to alter the child process's environment by passing a list of environment settings in the {{code|envp}} argument. This argument is an array of character pointers; each pointer (except for the last one) points to a null-terminated string defining an environment variable. An environment variable has the form: ''name''=''value'' where {{code|name}} is the variable name and {{code|value}} is its value. The last pointer in the array is null. When the {{code|envp}} argument is null, the child inherits the parent's environment settings.
Under Microsoft Windows, the {{mono|spawn*}} functions use {{code|LoadModule}} to run the spawned process; and if this fails, an attempt is made to spawn a normal MS-DOS process. If a Windows application is spawned, the instance handle can be obtained using {{code|exec_instancehandleget}}. It is possible to specify how the spawned program will be shown using the functions {{code|_exec_showset}}, {{code|_exec_showget}}, and {{code|_exec_showreset}}.{{disputed inline|talk=Talk:Spawn (computing)#Possibly-bogus claims about spawn* in Windows|date=October 2025}}
===Return values=== The return value indicates the exit status of the spawned program. A value of zero indicates that the spawned program executed successfully. A positive value indicates that the spawned program executed, but was aborted or ended in error, the value returned is the exit status of the child process. A negative value indicates that the spawned program did not execute, and {{code|errno}} is set. Under Microsoft Windows, {{code|spawn}} returns the negated error code returned from {{code|LoadModule}} for compatibility with the C run-time library. The following error codes may be encountered: {| class="wikitable" |- ! Value || Notes |- | <code>-2 </code> || File not found |- | <code>-3 </code> || Path not found |- | <code>-11 </code> || Invalid {{mono|.exe}} file (for Windows) |- | <code>-13 </code> || DOS 4. 0 application |- | <code>-14 </code> || Unknown {{mono|.exe}} type (may be DOS extended) |- |}
==POSIX spawn functions== The {{man/format|3p|posix_spawn|http://pubs.opengroup.org/onlinepubs/9699919799/functions/posix_spawn.html}} and its sibling <code>posix_spawnp</code> can be used as replacements for <code>fork</code> and <code>exec</code>, but does not provide the same flexibility as using <code>fork</code> and <code>exec</code> separately. They may be efficient replacements for <code>fork</code> and <code>exec</code>, but their purpose is to provide process creation primitives in embedded environments where <code>fork</code> is not supported due to lack of dynamic address translation; however, may Unix-like operating systems with full dynamic address translation support also implement them.
==History==
The {{code|spawn}} metaphor, i.e., to produce offspring as in egg deposition, had its early use in the VMS, now OpenVMS, operating system (1977). In academia, there existed a lively debate between proponents of the Unix {{code|fork}} (crude copy of memory layout, but fast) versus VMS's {{code|spawn}} (reliable construction of process parameters, but slower). This debate revived when the VMS spawning mechanism was inherited by Windows NT (1993).
==See also== * Fork * Exec * fork-exec * PATH (variable) * Process.h
==Notes== {{Notelist}}
==References== {{Reflist}}
Category:Process (computing) Category:C POSIX library Category:Process.h