1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2015 Joyent, Inc. 13.\" 14.Dd May 11, 2016 15.Dt PCREATE 3PROC 16.Os 17.Sh NAME 18.Nm Pcreate , 19.Nm Pxcreate , 20.Nm Pcreate_callback 21.Nd create and control a process 22.Sh SYNOPSIS 23.Lb libproc 24.In libproc.h 25.Ft "struct ps_prochandle *" 26.Fo Pcreate 27.Fa "const char *file" 28.Fa "char *const *argv" 29.Fa "int *perr" 30.Fa "char *path" 31.Fa "size_t len" 32.Fc 33.Ft "struct ps_prochandle *" 34.Fo Pxcreate 35.Fa "const char *file" 36.Fa "char *const *argv" 37.Fa "char *const *envp" 38.Fa "int *perr" 39.Fa "char *path" 40.Fa "size_t len" 41.Fc 42.Ft void 43.Fo Pcreate_callback 44.Fa "struct ps_prochandle *P" 45.Fc 46.Sh DESCRIPTION 47The 48.Fn Pcreate 49function creates a process controlled by the 50.Sy libproc 51library. 52The 53.Fn Pxcreate 54function does the same while also allowing the replacement of the 55environment via 56.Fa envp . 57.Pp 58Both functions cause the caller to 59.Xr fork 2 . 60Followed by the child calling 61.Xr exec 2 62to load the new process image specified by 63.Fa file . 64The 65.Ev PATH 66is searched for 67.Fa file 68if it is not an absolute path, similar to 69.Xr execvp 2 . 70.Pp 71The process image will be invoked with the arguments specified by 72.Fa argv , 73which should be a 74.Dv NULL Ns -terminated 75array of character strings. 76Each entry in the array is an individual argument. 77The environment of the process image will be inherited from the running process 78if the 79.Fn Pcreate 80function is called or if the 81.Fn Pxcreate 82function is called and the value of 83.Fa envp 84is 85.Dv NULL . 86Otherwise, 87.Fa envp 88should be a 89.Dv NULL Ns -terminated 90array of character strings whose entries are in the form of 91.Em key=value . 92For more on the process environment, see 93.Xr environ 5 . 94.Pp 95The 96.Fn Pcreate_callback 97function allows a way for callers to inject a callback into the child 98process before the call to 99.Xr exec 2 . 100The symbol 101.Sy Pcreate_callback 102is a symbol that may be interposed on by consumers. 103It allows the chance for the modification of signal dispositions or any other 104changes that a caller may wish to make. 105.Pp 106If the caller's real user or group ID is not their effective user or 107group ID, then the child process's user and group IDs will all be reset 108to the real user and group id. 109.Pp 110The 111.Fa perr 112argument must be a 113.Pf non- Dv NULL 114pointer. 115If the 116.Fn Pcreate 117or 118.Fn Pxcreate 119functions fail, the value pointed to will be filled in with a more 120detailed error code listed in 121.Sx ERRORS . 122A human-readable error message is obtained with 123.Xr Pcreate_error 3PROC . 124.Pp 125Multiple executables named 126.Fa file 127may exist on the 128.Fa PATH . 129To determine the full path of the executable pass a non-NULL 130.Fa path 131pointer. 132Upon successful completion of 133.Fn Pcreate 134or 135.Fn Pxcreate 136the 137.Fa path 138pointer will contain the full path up to 139.Fa len 140bytes, including the NUL character. 141.Pp 142Upon successful completion of the 143.Fn Pcreate 144or 145.Fn Pxcreate 146function, a handle to the process is returned. 147This handle is usable with other 148.Sy libproc 149routines and will persist until either 150.Xr Pfree 3PROC 151or 152.Xr Prelease 3PROC 153is called on the resulting handle. 154The process created is stopped just after return from the 155.Xr exec 2 156family of system calls. 157The process will not run, unless the caller sets it running or releases its 158handle to the process. 159.Pp 160A 32-bit process cannot use this interface to launch or control a 16164-bit process. 162However, a 64-bit process can create and control both 32-bit and 64-bit 163processes. 164.Sh RETURN VALUES 165Upon successful completion, both the 166.Fn Pcreate 167and 168.Fn Pxcreate 169functions create a new process and return a 170.Sy libproc 171handle to it. 172Otherwise, 173.Sy NULL 174is returned and 175.Fa perr 176is filled in with the corresponding error. 177.Sh ERRORS 178The 179.Fn Pcreate 180and 181.Fn Pxcreate 182functions will fail if: 183.Bl -tag -width Er 184.It Er C_FORK 185The call to 186.Xr fork 2 187failed. 188.It Er C_INTR 189The operation was interrupted by a signal. 190.It Er C_LP64 191The calling process is 32-bit, but it attempted to control a 64-bit 192process. 193.It Er C_NOEXEC 194The specified 195.Fa file 196or the one found by searching 197.Dv PATH 198cannot be executed. 199.It Er C_NOENT 200The specified 201.Fa file 202does not exist or it could not be found by searching 203.Dv PATH . 204.It Er C_PERM 205The specified 206.Fa file 207or the one found by searching 208.Dv PATH 209is set-id or unreadable. 210.It Er C_STRANGE 211An unanticipated system error occurred while trying to create the 212process and its handle. 213When this occurs, then the value of 214.Sy errno 215is meaningful. 216See 217.Xr errno 3C 218for more information and 219.Xr Intro 2 220for the list of possible errors. 221.El 222.Sh INTERFACE STABILITY 223.Sy Uncommitted 224.Sh MT-LEVEL 225.Sy MT-Safe 226.Sh SEE ALSO 227.Xr exec 2 , 228.Xr execvp 2 , 229.Xr fork 2 , 230.Xr Intro 2 , 231.Xr errno 3C , 232.Xr libproc 3LIB , 233.Xr Pcreate_error 3PROC , 234.Xr Pfree 3PROC , 235.Xr Prelease 3PROC 236