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