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

NAME

6       explain_wait - explain wait(2) errors
7

SYNOPSIS

9       #include <libexplain/wait.h>
10       const char *explain_wait(int *status);
11       const char *explain_errno_wait(int errnum, int *status);
12       void  explain_message_wait(char  *message,  int message_size, int *sta‐
13       tus);
14       void explain_message_errno_wait(char *message,  int  message_size,  int
15       errnum, int *status);
16

DESCRIPTION

18       These  functions may be used to obtain explanations for errors returned
19       by the wait(2) system call.
20
21   explain_wait
22       const char *explain_wait(int *status);
23
24       The explain_wait function is used to obtain an explanation of an  error
25       returned  by  the wait(2) system call.  The least the message will con‐
26       tain is the value of strerror(errno), but usually it will do much  bet‐
27       ter, and indicate the underlying cause in more detail.
28
29       The  errno global variable will be used to obtain the error value to be
30       decoded.
31
32       This function is intended to be used in a fashion similar to  the  fol‐
33       lowing example:
34              if (wait(status) < 0)
35              {
36                  fprintf(stderr, "%s\n", explain_wait(status));
37                  exit(EXIT_FAILURE);
38              }
39
40       status  The  original  status,  exactly as passed to the wait(2) system
41               call.
42
43       Returns:
44               The message explaining  the  error.   This  message  buffer  is
45               shared by all libexplain functions which do not supply a buffer
46               in their argument list.  This will be overwritten by  the  next
47               call  to  any  libexplain  function  which  shares this buffer,
48               including other threads.
49
50       Note: This function is not thread safe, because it shares a return buf‐
51       fer across all threads, and many other functions in this library.
52
53   explain_errno_wait
54       const char *explain_errno_wait(int errnum, int *status);
55
56       The  explain_errno_wait function is used to obtain an explanation of an
57       error returned by the wait(2) system call.  The least the message  will
58       contain  is  the value of strerror(errnum), but usually it will do much
59       better, and indicate the underlying cause in more detail.
60
61       This function is intended to be used in a fashion similar to  the  fol‐
62       lowing example:
63              if (wait(status) < 0)
64              {
65                  int err = errno;
66                  fprintf(stderr, "%s\n", explain_errno_wait(err, status));
67                  exit(EXIT_FAILURE);
68              }
69
70       errnum  The  error value to be decoded, usually obtained from the errno
71               global variable just before this function is called.   This  is
72               necessary  if you need to call any code between the system call
73               to be explained and this function, because many libc  functions
74               will alter the value of errno.
75
76       status  The  original  status,  exactly as passed to the wait(2) system
77               call.
78
79       Returns:
80               The message explaining  the  error.   This  message  buffer  is
81               shared by all libexplain functions which do not supply a buffer
82               in their argument list.  This will be overwritten by  the  next
83               call  to  any  libexplain  function  which  shares this buffer,
84               including other threads.
85
86       Note: This function is not thread safe, because it shares a return buf‐
87       fer across all threads, and many other functions in this library.
88
89   explain_message_wait
90       void  explain_message_wait(char  *message,  int message_size, int *sta‐
91       tus);
92
93       The explain_message_wait function may be used to  obtain an explanation
94       of an error returned by the wait(2) system call.  The least the message
95       will contain is the value of strerror(errno), but usually  it  will  do
96       much better, and indicate the underlying cause in more detail.
97
98       The  errno global variable will be used to obtain the error value to be
99       decoded.
100
101       This function is intended to be used in a fashion similar to  the  fol‐
102       lowing example:
103              if (wait(status) < 0)
104              {
105                  char message[3000];
106                  explain_message_wait(message, sizeof(message), status);
107                  fprintf(stderr, "%s\n", message);
108                  exit(EXIT_FAILURE);
109              }
110
111       message The  location  in  which  to  store the returned message.  If a
112               suitable message return buffer is supplied,  this  function  is
113               thread safe.
114
115       message_size
116               The  size  in  bytes  of  the  location  in  which to store the
117               returned message.
118
119       status  The original status, exactly as passed to  the  wait(2)  system
120               call.
121
122   explain_message_errno_wait
123       void  explain_message_errno_wait(char  *message,  int message_size, int
124       errnum, int *status);
125
126       The explain_message_errno_wait function may be used to obtain an expla‐
127       nation  of an error returned by the wait(2) system call.  The least the
128       message will contain is the value of strerror(errnum), but  usually  it
129       will do much better, and indicate the underlying cause in more detail.
130
131       This  function  is intended to be used in a fashion similar to the fol‐
132       lowing example:
133              if (wait(status) < 0)
134              {
135                  int err = errno;
136                  char message[3000];
137                  explain_message_errno_wait(message, sizeof(message), err, status);
138                  fprintf(stderr, "%s\n", message);
139                  exit(EXIT_FAILURE);
140              }
141
142       message The location in which to store  the  returned  message.   If  a
143               suitable  message  return  buffer is supplied, this function is
144               thread safe.
145
146       message_size
147               The size in bytes  of  the  location  in  which  to  store  the
148               returned message.
149
150       errnum  The  error value to be decoded, usually obtained from the errno
151               global variable just before this function is called.   This  is
152               necessary  if you need to call any code between the system call
153               to be explained and this function, because many libc  functions
154               will alter the value of errno.
155
156       status  The  original  status,  exactly as passed to the wait(2) system
157               call.
158

SEE ALSO

160       wait(2) wait for process to change state
161
162       explain_wait_or_die(3)
163               wait for process to change state and report errors
164
166       libexplain version 1.4
167       Copyright (C) 2008 Peter Miller
168
169
170
171                                                               explain_wait(3)
Impressum