1explain_setpgrp(3) Library Functions Manual explain_setpgrp(3)
2
6 explain_setpgrp - explain setpgrp(2) errors
7
9 #include <libexplain/setpgrp.h>
10 const char *explain_setpgrp(pid_t pid, pid_t pgid);
11 const char *explain_errno_setpgrp(int errnum, pid_t pid, pid_t pgid);
12 void explain_message_setpgrp(char *message, int message_size, pid_t
13 pid, pid_t pgid);
14 void explain_message_errno_setpgrp(char *message, int message_size, int
15 errnum, pid_t pid, pid_t pgid);
16
18 These functions may be used to obtain explanations for errors returned
19 by the setpgrp(2) system call.
20 Note: the setpgrp(2) function has two implementations. The System V
22 version has no arguments, while the BSD version has two arguments. For
23 simplicity of implementation, the argument list seen here includes the
24 pid and pgid arguments.
25 The System V getpgid() semantics can be obtained by calling setpgrp(0,
27 0) on systems with the BSD version, and this is the API for libexplain,
28 even on systems that do not use the BSD API.
29 explain_setpgrp
31 const char *explain_setpgrp(pid_t pid, pid_t pgid);
32 The explain_setpgrp function is used to obtain an explanation of an
34 error returned by the setpgrp(2) system call. The least the message
35 will contain is the value of strerror(errno), but usually it will do
36 much better, and indicate the underlying cause in more detail.
37 The errno global variable will be used to obtain the error value to be
39 decoded.
40 pid The original pid, exactly as passed to the setpgrp(2) system
42 call.
43 pgid The original pgid, exactly as passed to the setpgrp(2) system
45 call.
46 Returns:
48 The message explaining the error. This message buffer is shared
49 by all libexplain functions which do not supply a buffer in
50 their argument list. This will be overwritten by the next call
51 to any libexplain function which shares this buffer, including
52 other threads.
53 Note: This function is not thread safe, because it shares a return buf‐
55 fer across all threads, and many other functions in this library.
56 Example: This function is intended to be used in a fashion similar to
58 the following example:
59 if (setpgrp(pid, pgid) < 0)
60 {
61 fprintf(stderr, "%s\n", explain_setpgrp(pid, pgid));
62 exit(EXIT_FAILURE);
63 }
64 The above code example is available pre-packaged as the explain_setp‐
66 grp_or_die(3) function.
67 explain_errno_setpgrp
69 const char *explain_errno_setpgrp(int errnum, pid_t pid, pid_t pgid);
70 The explain_errno_setpgrp function is used to obtain an explanation of
72 an error returned by the setpgrp(2) system call. The least the message
73 will contain is the value of strerror(errno), but usually it will do
74 much better, and indicate the underlying cause in more detail.
75 errnum The error value to be decoded, usually obtained from the errno
77 global variable just before this function is called. This is
78 necessary if you need to call any code between the system call
79 to be explained and this function, because many libc functions
80 will alter the value of errno.
81 pid The original pid, exactly as passed to the setpgrp(2) system
83 call.
84 pgid The original pgid, exactly as passed to the setpgrp(2) system
86 call.
87 Returns:
89 The message explaining the error. This message buffer is shared
90 by all libexplain functions which do not supply a buffer in
91 their argument list. This will be overwritten by the next call
92 to any libexplain function which shares this buffer, including
93 other threads.
94 Note: This function is not thread safe, because it shares a return buf‐
96 fer across all threads, and many other functions in this library.
97 Example: This function is intended to be used in a fashion similar to
99 the following example:
100 if (setpgrp(pid, pgid) < 0)
101 {
102 int err = errno;
103 fprintf(stderr, "%s\n", explain_errno_setpgrp(err, pid,
104 pgid));
105 exit(EXIT_FAILURE);
106 }
107 The above code example is available pre-packaged as the explain_setp‐
109 grp_or_die(3) function.
110 explain_message_setpgrp
112 void explain_message_setpgrp(char *message, int message_size, pid_t
113 pid, pid_t pgid);
114 The explain_message_setpgrp function is used to obtain an explanation
116 of an error returned by the setpgrp(2) system call. The least the mes‐
117 sage will contain is the value of strerror(errno), but usually it will
118 do much better, and indicate the underlying cause in more detail.
119 The errno global variable will be used to obtain the error value to be
121 decoded.
122 message The location in which to store the returned message. If a suit‐
124 able message return buffer is supplied, this function is thread
125 safe.
126 message_size
128 The size in bytes of the location in which to store the
129 returned message.
130 pid The original pid, exactly as passed to the setpgrp(2) system
132 call.
133 pgid The original pgid, exactly as passed to the setpgrp(2) system
135 call.
136 Example: This function is intended to be used in a fashion similar to
138 the following example:
139 if (setpgrp(pid, pgid) < 0)
140 {
141 char message[3000];
142 explain_message_setpgrp(message, sizeof(message), pid,
143 pgid);
144 fprintf(stderr, "%s\n", message);
145 exit(EXIT_FAILURE);
146 }
147 The above code example is available pre-packaged as the explain_setp‐
149 grp_or_die(3) function.
150 explain_message_errno_setpgrp
152 void explain_message_errno_setpgrp(char *message, int message_size, int
153 errnum, pid_t pid, pid_t pgid);
154 The explain_message_errno_setpgrp function is used to obtain an expla‐
156 nation of an error returned by the setpgrp(2) system call. The least
157 the message will contain is the value of strerror(errno), but usually
158 it will do much better, and indicate the underlying cause in more
159 detail.
160 message The location in which to store the returned message. If a suit‐
162 able message return buffer is supplied, this function is thread
163 safe.
164 message_size
166 The size in bytes of the location in which to store the
167 returned message.
168 errnum The error value to be decoded, usually obtained from the errno
170 global variable just before this function is called. This is
171 necessary if you need to call any code between the system call
172 to be explained and this function, because many libc functions
173 will alter the value of errno.
174 pid The original pid, exactly as passed to the setpgrp(2) system
176 call.
177 pgid The original pgid, exactly as passed to the setpgrp(2) system
179 call.
180 Example: This function is intended to be used in a fashion similar to
182 the following example:
183 if (setpgrp(pid, pgid) < 0)
184 {
185 int err = errno;
186 char message[3000];
187 explain_message_errno_setpgrp(message, sizeof(message), err,
188 pid, pgid);
189 fprintf(stderr, "%s\n", message);
190 exit(EXIT_FAILURE);
191 }
192 The above code example is available pre-packaged as the explain_setp‐
194 grp_or_die(3) function.
195
197 setpgrp(2)
198 set process group
199 explain_setpgrp_or_die(3)
201 set process group and report errors
202
204 libexplain version 1.4
205 Copyright (C) 2011 Peter Miller
206 explain_setpgrp(3)