1.\" $OpenBSD: posix_spawn.3,v 1.9 2017/10/17 22:47:58 schwarze Exp $ 2.\" 3.\" Copyright (c) 2012 Marc Espie <espie@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: October 17 2017 $ 18.Dt POSIX_SPAWN 3 19.Os 20.Sh NAME 21.Nm posix_spawn , posix_spawnp 22.Nd launch external command 23.Sh SYNOPSIS 24.In spawn.h 25.Ft int 26.Fn posix_spawn "pid_t *restrict pidp" "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]" 27.Ft int 28.Fn posix_spawnp "pid_t *restrict pidp" "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]" 29.Sh DESCRIPTION 30The 31.Fn posix_spawn 32function forks a new process and starts an external program from 33pathname 34.Fa path . 35.Pp 36The 37.Fn posix_spawnp 38function is similar, except it constructs the pathname from 39.Fa file 40following the usual 41.Ev PATH 42handling rules: 43if file contains a slash, then it is directly used as a path. 44Otherwise, 45.Fn posix_spawnp 46searches every directory mentioned in 47.Ev PATH 48until it finds an executable. 49If 50.Ev PATH 51is not set, the default is 52.Dq /usr/bin:/bin . 53.Pp 54Arguments to the new process are passed to 55.Xr execve 2 56as 57.Fa argv 58and 59.Fa envp . 60If 61.Fa envp 62is NULL, the environment is passed unchanged from the parent process. 63.Pp 64If 65.Fa file_actions 66is a null pointer, file descriptors open in the parent process 67follow the usual rules: they remain open in the child process unless they've 68been marked 69.Dv FD_CLOEXEC 70with 71.Xr fcntl 2 . 72.Pp 73Otherwise, file descriptors in the child process 74are altered according to 75.Xr posix_spawn_file_actions_init 3 , 76.Xr posix_spawn_file_actions_addclose 3 , 77.Xr posix_spawn_file_actions_adddup2 3 , 78and 79.Xr posix_spawn_file_actions_addopen 3 . 80.Pp 81The 82.Fa attrp 83argument can be used to control signal, UID and GID handling in the 84child process. 85.Pp 86If 87.Fa attrp 88is NULL, default values are used: caught signals in the parent 89process are set to the default value in the child process, and ignored signals 90stay ignored. 91.Pp 92See 93.Xr posix_spawnattr_setflags 3 94for attribute details. 95.Sh RETURN VALUES 96Upon successful completion, both functions return 0. 97If 98.Fa pidp 99is not a NULL pointer, 100.Li *pidp 101gets set to the PID of the newly created child process. 102.Pp 103In case of an error, both functions may return 104.Fn fork 105or 106.Fn exec 107return values and set 108.Va errno 109accordingly. 110.Pp 111Note, however, that after the new process is started, the child 112process has no way to return an error value. 113In case of a problem, the child process will instead exit 114with exit status 127. 115.Sh SEE ALSO 116.Xr execve 2 , 117.Xr fork 2 , 118.Xr posix_spawn_file_actions_addclose 3 , 119.Xr posix_spawn_file_actions_init 3 , 120.Xr posix_spawnattr_init 3 , 121.Xr posix_spawnattr_setflags 3 122.Sh STANDARDS 123Both functions conform to 124.St -p1003.1-2001 . 125.Sh HISTORY 126These functions were ported from 127.Fx 128to 129.Ox 5.2 . 130.Sh AUTHORS 131.An \&Ed Shouten Aq Mt ed@FreeBSD.org 132