1explain_getpgrp(3) Library Functions Manual explain_getpgrp(3)
2
6 explain_getpgrp - explain getpgrp(2) errors
7
9 #include <libexplain/getpgrp.h>
10 const char *explain_getpgrp(pid_t pid);
11 const char *explain_errno_getpgrp(int errnum, pid_t pid);
12 void explain_message_getpgrp(char *message, int message_size, pid_t
13 pid);
14 void explain_message_errno_getpgrp(char *message, int message_size, int
15 errnum, pid_t pid);
16
18 These functions may be used to obtain explanations for errors returned
19 by the getpgrp(2) system call.
20 Note: the getpgrp(2) function has two implementations. The POSIX.1
22 version has no arguments, while the BSD version has one argument. For
23 simplicity of implementation, the argument list seen here includes the
24 pid argument.
25 The POSIX.1 getpgid() semantics can be obtained by calling getpgrp(0)
27 on BSD systems, and this is the API for libexplain, even on systems
28 that do not use the BSD API.
29 explain_getpgrp
31 const char *explain_getpgrp(pid_t pid);
32 The explain_getpgrp function is used to obtain an explanation of an
34 error returned by the getpgrp(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 getpgrp(2) system
42 call.
43 Returns:
45 The message explaining the error. This message buffer is shared
46 by all libexplain functions which do not supply a buffer in
47 their argument list. This will be overwritten by the next call
48 to any libexplain function which shares this buffer, including
49 other threads.
50 Note: This function is not thread safe, because it shares a return buf‐
52 fer across all threads, and many other functions in this library.
53 Example: This function is intended to be used in a fashion similar to
55 the following example:
56 pid_t result = getpgrp(pid);
57 if (result < 0)
58 {
59 fprintf(stderr, "%s\n", explain_getpgrp(pid));
60 exit(EXIT_FAILURE);
61 }
62 The above code example is available pre-packaged as the explain_getp‐
64 grp_or_die(3) function.
65 explain_errno_getpgrp
67 const char *explain_errno_getpgrp(int errnum, pid_t pid);
68 The explain_errno_getpgrp function is used to obtain an explanation of
70 an error returned by the getpgrp(2) system call. The least the message
71 will contain is the value of strerror(errno), but usually it will do
72 much better, and indicate the underlying cause in more detail.
73 errnum The error value to be decoded, usually obtained from the errno
75 global variable just before this function is called. This is
76 necessary if you need to call any code between the system call
77 to be explained and this function, because many libc functions
78 will alter the value of errno.
79 pid The original pid, exactly as passed to the getpgrp(2) system
81 call.
82 Returns:
84 The message explaining the error. This message buffer is shared
85 by all libexplain functions which do not supply a buffer in
86 their argument list. This will be overwritten by the next call
87 to any libexplain function which shares this buffer, including
88 other threads.
89 Note: This function is not thread safe, because it shares a return buf‐
91 fer across all threads, and many other functions in this library.
92 Example: This function is intended to be used in a fashion similar to
94 the following example:
95 pid_t result = getpgrp(pid);
96 if (result < 0)
97 {
98 int err = errno;
99 fprintf(stderr, "%s\n", explain_errno_getpgrp(err, pid));
100 exit(EXIT_FAILURE);
101 }
102 The above code example is available pre-packaged as the explain_getp‐
104 grp_or_die(3) function.
105 explain_message_getpgrp
107 void explain_message_getpgrp(char *message, int message_size, pid_t
108 pid);
109 The explain_message_getpgrp function is used to obtain an explanation
111 of an error returned by the getpgrp(2) system call. The least the mes‐
112 sage will contain is the value of strerror(errno), but usually it will
113 do much better, and indicate the underlying cause in more detail.
114 The errno global variable will be used to obtain the error value to be
116 decoded.
117 message The location in which to store the returned message. If a suit‐
119 able message return buffer is supplied, this function is thread
120 safe.
121 message_size
123 The size in bytes of the location in which to store the
124 returned message.
125 pid The original pid, exactly as passed to the getpgrp(2) system
127 call.
128 Example: This function is intended to be used in a fashion similar to
130 the following example:
131 pid_t result = getpgrp(pid);
132 if (result < 0)
133 {
134 char message[3000];
135 explain_message_getpgrp(message, sizeof(message), pid);
136 fprintf(stderr, "%s\n", message);
137 exit(EXIT_FAILURE);
138 }
139 The above code example is available pre-packaged as the explain_getp‐
141 grp_or_die(3) function.
142 explain_message_errno_getpgrp
144 void explain_message_errno_getpgrp(char *message, int message_size, int
145 errnum, pid_t pid);
146 The explain_message_errno_getpgrp function is used to obtain an expla‐
148 nation of an error returned by the getpgrp(2) system call. The least
149 the message will contain is the value of strerror(errno), but usually
150 it will do much better, and indicate the underlying cause in more
151 detail.
152 message The location in which to store the returned message. If a suit‐
154 able message return buffer is supplied, this function is thread
155 safe.
156 message_size
158 The size in bytes of the location in which to store the
159 returned message.
160 errnum The error value to be decoded, usually obtained from the errno
162 global variable just before this function is called. This is
163 necessary if you need to call any code between the system call
164 to be explained and this function, because many libc functions
165 will alter the value of errno.
166 pid The original pid, exactly as passed to the getpgrp(2) system
168 call.
169 Example: This function is intended to be used in a fashion similar to
171 the following example:
172 pid_t result = getpgrp(pid);
173 if (result < 0)
174 {
175 int err = errno;
176 char message[3000];
177 explain_message_errno_getpgrp(message, sizeof(message), err,
178 pid);
179 fprintf(stderr, "%s\n", message);
180 exit(EXIT_FAILURE);
181 }
182 The above code example is available pre-packaged as the explain_getp‐
184 grp_or_die(3) function.
185
187 getpgrp(2)
188 get process group
189 explain_getpgrp_or_die(3)
191 get process group and report errors
192
194 libexplain version 1.4
195 Copyright (C) 2011 Peter Miller
196 explain_getpgrp(3)