1explain_wait3(3)           Library Functions Manual           explain_wait3(3)
2
3
4

NAME

6       explain_wait3 - explain wait3(2) errors
7

SYNOPSIS

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

DESCRIPTION

20       These  functions may be used to obtain explanations for errors returned
21       by the wait3(2) system call.
22
23   explain_wait3
24       const char  *explain_wait3(int  *status,  int  options,  struct  rusage
25       *rusage);
26
27       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
32       The errno global variable will be used to obtain the error value to  be
33       decoded.
34
35       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
44       status  The original status, exactly as passed to the  wait3(2)  system
45               call.
46
47       options The  original options, exactly as passed to the wait3(2) system
48               call.
49
50       rusage  The original rusage, exactly as passed to the  wait3(2)  system
51               call.
52
53       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
60       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
63   explain_errno_wait3
64       const char *explain_errno_wait3(int errnum, int *status,  int  options,
65       struct rusage *rusage);
66
67       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
72       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
83       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
89       status  The  original  status, exactly as passed to the wait3(2) system
90               call.
91
92       options The original options, exactly as passed to the wait3(2)  system
93               call.
94
95       rusage  The  original  rusage, exactly as passed to the wait3(2) system
96               call.
97
98       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
105       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
108   explain_message_wait3
109       void  explain_message_wait3(char  *message, int message_size, int *sta‐
110       tus, int options, struct rusage *rusage);
111
112       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
117       The  errno global variable will be used to obtain the error value to be
118       decoded.
119
120       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
132       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
136       message_size
137               The  size  in  bytes  of  the  location  in  which to store the
138               returned message.
139
140       status  The original status, exactly as passed to the  wait3(2)  system
141               call.
142
143       options The  original options, exactly as passed to the wait3(2) system
144               call.
145
146       rusage  The original rusage, exactly as passed to the  wait3(2)  system
147               call.
148
149   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
153       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
159       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
172       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
176       message_size
177               The  size  in  bytes  of  the  location  in  which to store the
178               returned message.
179
180       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
186       status  The original status, exactly as passed to the  wait3(2)  system
187               call.
188
189       options The  original options, exactly as passed to the wait3(2) system
190               call.
191
192       rusage  The original rusage, exactly as passed to the  wait3(2)  system
193               call.
194

SEE ALSO

196       wait3(2)
197               wait for process to change state
198
199       explain_wait3_or_die(3)
200               wait for process to change state and report errors
201
203       libexplain version 0.40
204       Copyright (C) 2008 Peter Miller
205
206
207
208                                                              explain_wait3(3)
Impressum