1explain_wait4(3) Library Functions Manual explain_wait4(3)
2
6 explain_wait4 - explain wait4(2) errors
7
9 #include <libexplain/wait4.h>
10 const char *explain_wait4(int pid, int *status, int options, struct
11 rusage *rusage);
12 const char *explain_errno_wait4(int errnum, int pid, int *status, int
13 options, struct rusage *rusage);
14 void explain_message_wait4(char *message, int message_size, int pid,
15 int *status, int options, struct rusage *rusage);
16 void explain_message_errno_wait4(char *message, int message_size, int
17 errnum, int pid, int *status, int options, struct rusage *rusage);
18
20 These functions may be used to obtain explanations for errors returned
21 by the wait4(2) system call.
22 explain_wait4
24 const char *explain_wait4(int pid, int *status, int options, struct
25 rusage *rusage);
26 The explain_wait4 function is used to obtain an explanation of an error
28 returned by the wait4(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 if (wait4(pid, status, options, rusage) < 0)
38 {
39 fprintf(stderr, "%s\n", explain_wait4(pid, status, options, rusage));
40 exit(EXIT_FAILURE);
41 }
42 pid The original pid, exactly as passed to the wait4(2) system
44 call.
45 status The original status, exactly as passed to the wait4(2) system
47 call.
48 options The original options, exactly as passed to the wait4(2) system
50 call.
51 rusage The original rusage, exactly as passed to the wait4(2) system
53 call.
54 Returns:
56 The message explaining the error. This message buffer is
57 shared by all libexplain functions which do not supply a buffer
58 in their argument list. This will be overwritten by the next
59 call to any libexplain function which shares this buffer,
60 including other threads.
61 Note: This function is not thread safe, because it shares a return buf‐
63 fer across all threads, and many other functions in this library.
64 explain_errno_wait4
66 const char *explain_errno_wait4(int errnum, int pid, int *status, int
67 options, struct rusage *rusage);
68 The explain_errno_wait4 function is used to obtain an explanation of an
70 error returned by the wait4(2) system call. The least the message will
71 contain is the value of strerror(errnum), but usually it will do much
72 better, and indicate the underlying cause in more detail.
73 This function is intended to be used in a fashion similar to the fol‐
75 lowing example:
76 if (wait4(pid, status, options, rusage) < 0)
77 {
78 int err = errno;
79 fprintf(stderr, "%s\n", explain_errno_wait4(err,
80 pid, status, options, rusage));
81 exit(EXIT_FAILURE);
82 }
83 errnum The error value to be decoded, usually obtained from the errno
85 global variable just before this function is called. This is
86 necessary if you need to call any code between the system call
87 to be explained and this function, because many libc functions
88 will alter the value of errno.
89 pid The original pid, exactly as passed to the wait4(2) system
91 call.
92 status The original status, exactly as passed to the wait4(2) system
94 call.
95 options The original options, exactly as passed to the wait4(2) system
97 call.
98 rusage The original rusage, exactly as passed to the wait4(2) system
100 call.
101 Returns:
103 The message explaining the error. This message buffer is
104 shared by all libexplain functions which do not supply a buffer
105 in their argument list. This will be overwritten by the next
106 call to any libexplain function which shares this buffer,
107 including other threads.
108 Note: This function is not thread safe, because it shares a return buf‐
110 fer across all threads, and many other functions in this library.
111 explain_message_wait4
113 void explain_message_wait4(char *message, int message_size, int pid,
114 int *status, int options, struct rusage *rusage);
115 The explain_message_wait4 function may be used to obtain an explana‐
117 tion of an error returned by the wait4(2) system call. The least the
118 message will contain is the value of strerror(errno), but usually it
119 will do much better, and indicate the underlying cause in more detail.
120 The errno global variable will be used to obtain the error value to be
122 decoded.
123 This function is intended to be used in a fashion similar to the fol‐
125 lowing example:
126 if (wait4(pid, status, options, rusage) < 0)
127 {
128 char message[3000];
129 explain_message_wait4(message, sizeof(message),
130 pid, status, options, rusage);
131 fprintf(stderr, "%s\n", message);
132 exit(EXIT_FAILURE);
133 }
134 message The location in which to store the returned message. If a
136 suitable message return buffer is supplied, this function is
137 thread safe.
138 message_size
140 The size in bytes of the location in which to store the
141 returned message.
142 pid The original pid, exactly as passed to the wait4(2) system
144 call.
145 status The original status, exactly as passed to the wait4(2) system
147 call.
148 options The original options, exactly as passed to the wait4(2) system
150 call.
151 rusage The original rusage, exactly as passed to the wait4(2) system
153 call.
154 explain_message_errno_wait4
156 void explain_message_errno_wait4(char *message, int message_size, int
157 errnum, int pid, int *status, int options, struct rusage *rusage);
158 The explain_message_errno_wait4 function may be used to obtain an
160 explanation of an error returned by the wait4(2) system call. The
161 least the message will contain is the value of strerror(errnum), but
162 usually it will do much better, and indicate the underlying cause in
163 more detail.
164 This function is intended to be used in a fashion similar to the fol‐
166 lowing example:
167 if (wait4(pid, status, options, rusage) < 0)
168 {
169 int err = errno;
170 char message[3000];
171 explain_message_errno_wait4(message, sizeof(message), err,
172 pid, status, options, rusage);
173 fprintf(stderr, "%s\n", message);
174 exit(EXIT_FAILURE);
175 }
176 message The location in which to store the returned message. If a
178 suitable message return buffer is supplied, this function is
179 thread safe.
180 message_size
182 The size in bytes of the location in which to store the
183 returned message.
184 errnum The error value to be decoded, usually obtained from the errno
186 global variable just before this function is called. This is
187 necessary if you need to call any code between the system call
188 to be explained and this function, because many libc functions
189 will alter the value of errno.
190 pid The original pid, exactly as passed to the wait4(2) system
192 call.
193 status The original status, exactly as passed to the wait4(2) system
195 call.
196 options The original options, exactly as passed to the wait4(2) system
198 call.
199 rusage The original rusage, exactly as passed to the wait4(2) system
201 call.
202
204 wait4(2)
205 wait for process to change state
206 explain_wait4_or_die(3)
208 wait for process to change state and report errors
209
211 libexplain version 1.4
212 Copyright (C) 2008 Peter Miller
213 explain_wait4(3)