1explain_wait3(3) Library Functions Manual explain_wait3(3)
2
6 explain_wait3 - explain wait3(2) errors
7
9 #include <libexplain/wait3.h>
10 const char *explain_wait3(int *status, int options, struct rusage
11 *rusage);
12 const char *explain_errno_wait3(int errnum, int *status, int options,
13 struct rusage *rusage);
14 void explain_message_wait3(char *message, int message_size, int *sta‐
15 tus, int options, struct rusage *rusage);
16 void explain_message_errno_wait3(char *message, int message_size, int
17 errnum, int *status, int options, struct rusage *rusage);
18
20 These functions may be used to obtain explanations for errors returned
21 by the wait3(2) system call.
22 explain_wait3
24 const char *explain_wait3(int *status, int options, struct rusage
25 *rusage);
26 The explain_wait3 function is used to obtain an explanation of an error
28 returned by the wait3(2) system call. The least the message will con‐
29 tain is the value of strerror(errno), but usually it will do much bet‐
30 ter, and indicate the underlying cause in more detail.
31 The errno global variable will be used to obtain the error value to be
33 decoded.
34 This function is intended to be used in a fashion similar to the fol‐
36 lowing example:
37 int pid = wait3(status, options, rusage);
38 if (pid < 0)
39 {
40 fprintf(stderr, "%s\n", explain_wait3(status, options, rusage));
41 exit(EXIT_FAILURE);
42 }
43 status The original status, exactly as passed to the wait3(2) system
45 call.
46 options The original options, exactly as passed to the wait3(2) system
48 call.
49 rusage The original rusage, exactly as passed to the wait3(2) system
51 call.
52 Returns:
54 The message explaining the error. This message buffer is
55 shared by all libexplain functions which do not supply a buffer
56 in their argument list. This will be overwritten by the next
57 call to any libexplain function which shares this buffer,
58 including other threads.
59 Note: This function is not thread safe, because it shares a return buf‐
61 fer across all threads, and many other functions in this library.
62 explain_errno_wait3
64 const char *explain_errno_wait3(int errnum, int *status, int options,
65 struct rusage *rusage);
66 The explain_errno_wait3 function is used to obtain an explanation of an
68 error returned by the wait3(2) system call. The least the message will
69 contain is the value of strerror(errnum), but usually it will do much
70 better, and indicate the underlying cause in more detail.
71 This function is intended to be used in a fashion similar to the fol‐
73 lowing example:
74 int pid = wait3(status, options, rusage);
75 if (pid < 0)
76 {
77 int err = errno;
78 fprintf(stderr, "%s\n", explain_errno_wait3(err, status, options,
79 rusage));
80 exit(EXIT_FAILURE);
81 }
82 errnum The error value to be decoded, usually obtained from the errno
84 global variable just before this function is called. This is
85 necessary if you need to call any code between the system call
86 to be explained and this function, because many libc functions
87 will alter the value of errno.
88 status The original status, exactly as passed to the wait3(2) system
90 call.
91 options The original options, exactly as passed to the wait3(2) system
93 call.
94 rusage The original rusage, exactly as passed to the wait3(2) system
96 call.
97 Returns:
99 The message explaining the error. This message buffer is
100 shared by all libexplain functions which do not supply a buffer
101 in their argument list. This will be overwritten by the next
102 call to any libexplain function which shares this buffer,
103 including other threads.
104 Note: This function is not thread safe, because it shares a return buf‐
106 fer across all threads, and many other functions in this library.
107 explain_message_wait3
109 void explain_message_wait3(char *message, int message_size, int *sta‐
110 tus, int options, struct rusage *rusage);
111 The explain_message_wait3 function may be used to obtain an explana‐
113 tion of an error returned by the wait3(2) system call. The least the
114 message will contain is the value of strerror(errno), but usually it
115 will do much better, and indicate the underlying cause in more detail.
116 The errno global variable will be used to obtain the error value to be
118 decoded.
119 This function is intended to be used in a fashion similar to the fol‐
121 lowing example:
122 int pid = wait3(status, options, rusage);
123 if (pid < 0)
124 {
125 char message[3000];
126 explain_message_wait3(message, sizeof(message),
127 status, options, rusage);
128 fprintf(stderr, "%s\n", message);
129 exit(EXIT_FAILURE);
130 }
131 message The location in which to store the returned message. If a
133 suitable message return buffer is supplied, this function is
134 thread safe.
135 message_size
137 The size in bytes of the location in which to store the
138 returned message.
139 status The original status, exactly as passed to the wait3(2) system
141 call.
142 options The original options, exactly as passed to the wait3(2) system
144 call.
145 rusage The original rusage, exactly as passed to the wait3(2) system
147 call.
148 explain_message_errno_wait3
150 void explain_message_errno_wait3(char *message, int message_size, int
151 errnum, int *status, int options, struct rusage *rusage);
152 The explain_message_errno_wait3 function may be used to obtain an
154 explanation of an error returned by the wait3(2) system call. The
155 least the message will contain is the value of strerror(errnum), but
156 usually it will do much better, and indicate the underlying cause in
157 more detail.
158 This function is intended to be used in a fashion similar to the fol‐
160 lowing example:
161 int pid = wait3(status, options, rusage);
162 if (pid < 0)
163 {
164 int err = errno;
165 char message[3000];
166 explain_message_errno_wait3(message, sizeof(message), err,
167 status, options, rusage);
168 fprintf(stderr, "%s\n", message);
169 exit(EXIT_FAILURE);
170 }
171 message The location in which to store the returned message. If a
173 suitable message return buffer is supplied, this function is
174 thread safe.
175 message_size
177 The size in bytes of the location in which to store the
178 returned message.
179 errnum The error value to be decoded, usually obtained from the errno
181 global variable just before this function is called. This is
182 necessary if you need to call any code between the system call
183 to be explained and this function, because many libc functions
184 will alter the value of errno.
185 status The original status, exactly as passed to the wait3(2) system
187 call.
188 options The original options, exactly as passed to the wait3(2) system
190 call.
191 rusage The original rusage, exactly as passed to the wait3(2) system
193 call.
194
196 wait3(2)
197 wait for process to change state
198 explain_wait3_or_die(3)
200 wait for process to change state and report errors
201
203 libexplain version 1.4
204 Copyright (C) 2008 Peter Miller
205 explain_wait3(3)