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. The 52.Fn Pxcreate 53function does the same while also allowing the replacement of the 54environment via 55.Fa envp . 56.Pp 57Both functions cause the caller to 58.Xr fork 2 . 59Followed by the child calling 60.Xr exec 2 61to load the new process image specified by 62.Fa file . 63The 64.Ev PATH 65is searched for 66.Fa file 67if it is not an absolute path, similar to 68.Xr execvp 2 . 69.Pp 70The process image will be invoked with the arguments specified by 71.Fa argv , 72which should be a 73.Dv NULL Ns -terminated 74array of character strings. Each entry in the array is an individual 75argument. The environment of the process image will be inherited from 76the running process if the 77.Fn Pcreate 78function is called or if the 79.Fn Pxcreate 80function is called and the value of 81.Fa envp 82is 83.Dv NULL . 84Otherwise, 85.Fa envp 86should be a 87.Dv NULL Ns -terminated 88array of character strings whose entries are in the form of 89.Em key=value . 90For more on the process environment, see 91.Xr environ 5 . 92.Pp 93The 94.Fn Pcreate_callback 95function allows a way for callers to inject a callback into the child 96process before the call to 97.Xr exec 2 . 98The symbol 99.Sy Pcreate_callback 100is a symbol that may be interposed on by consumers. It allows the chance 101for the modification of signal dispositions or any other changes that a 102caller may wish to make. 103.Pp 104If the caller's real user or group ID is not their effective user or 105group ID, then the child process's user and group IDs will all be reset 106to the real user and group id. 107.Pp 108The 109.Fa perr 110argument must be a 111.Pf non- Dv NULL 112pointer. If the 113.Fn Pcreate 114or 115.Fn Pxcreate 116functions fail, the value pointed to will be filled in with a more 117detailed error code listed in 118.Sx ERRORS . 119A human-readable error message is obtained with 120.Xr Pcreate_error 3PROC . 121.Pp 122Multiple executables named 123.Fa file 124may exist on the 125.Fa PATH . 126To determine the full path of the executable pass a non-NULL 127.Fa path 128pointer. Upon succesful completion of 129.Fn Pcreate 130or 131.Fn Pxcreate 132the 133.Fa path 134pointer will contain the full path up to 135.Fa len 136bytes, including the NUL character. 137.Pp 138Upon successful completion of the 139.Fn Pcreate 140or 141.Fn Pxcreate 142function, a handle to the process is returned. This handle is usable 143with other 144.Sy libproc 145routines and will persist until either 146.Xr Pfree 3PROC 147or 148.Xr Prelease 3PROC 149is called on the resulting handle. The process created is stopped just 150after return from the 151.Xr exec 2 152family of system calls. The process will not run, unless the caller sets 153it running or releases its handle to the process. 154.Pp 155A 32-bit process cannot use this interface to launch or control a 15664-bit process. However, a 64-bit process can create and control both 15732-bit and 64-bit processes. 158.Sh RETURN VALUES 159Upon successful completion, both the 160.Fn Pcreate 161and 162.Fn Pxcreate 163functions create a new process and return a 164.Sy libproc 165handle to it. Otherwise, 166.Sy NULL 167is returned and 168.Fa perr 169is filled in with the corresponding error. 170.Sh ERRORS 171The 172.Fn Pcreate 173and 174.Fn Pxcreate 175functions will fail if: 176.Bl -tag -width Er 177.It Er C_FORK 178The call to 179.Xr fork 2 180failed. 181.It Er C_INTR 182The operation was interrupted by a signal. 183.It Er C_LP64 184The calling process is 32-bit, but it attempted to control a 64-bit 185process. 186.It Er C_NOEXEC 187The specified 188.Fa file 189or the one found by searching 190.Dv PATH 191cannot be executed. 192.It Er C_NOENT 193The specified 194.Fa file 195does not exist or it could not be found by searching 196.Dv PATH . 197.It Er C_PERM 198The specified 199.Fa file 200or the one found by searching 201.Dv PATH 202is set-id or unreadable. 203.It Er C_STRANGE 204An unanticipated system error occurred while trying to create the 205process and its handle. When this occurs, then the value of 206.Sy errno 207is meaningful. See 208.Xr errno 3C 209for more information and 210.Xr Intro 2 211for the list of possible errors. 212.El 213.Sh INTERFACE STABILITY 214.Sy Uncommitted 215.Sh MT-LEVEL 216.Sy MT-Safe 217.Sh SEE ALSO 218.Xr exec 2 , 219.Xr execvp 2 , 220.Xr fork 2 , 221.Xr Intro 2 , 222.Xr errno 3C , 223.Xr libproc 3LIB , 224.Xr Pcreate_error 3PROC , 225.Xr Pfree 3PROC , 226.Xr Prelease 3PROC 227