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