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