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