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