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

NAME

6       explain_poll - explain poll(2) errors
7

SYNOPSIS

9       #include <libexplain/poll.h>
10       const char *explain_poll(struct pollfd *fds, int nfds, int timeout);
11       const char *explain_errno_poll(int errnum, struct pollfd *fds, int
12       nfds, int timeout);
13       void explain_message_poll(char *message, int message_size, struct
14       pollfd *fds, int nfds, int timeout);
15       void explain_message_errno_poll(char *message, int message_size, int
16       errnum, struct pollfd *fds, int nfds, int timeout);
17

DESCRIPTION

19       These functions may be used to obtain explanations for errors  returned
20       by the poll(2) system call.
21
22   explain_poll
23       const char *explain_poll(struct pollfd *fds, int nfds, int timeout);
24
25       The  explain_poll function is used to obtain an explanation of an error
26       returned by the poll(2) system call. The least the message will contain
27       is  the  value  of strerror(errno), but usually it will do much better,
28       and indicate the underlying cause in more detail.
29
30       The errno global variable will be used to obtain the error value to  be
31       decoded.
32
33       fds     The original fds, exactly as passed to the poll(2) system call.
34
35       nfds    The  original  nfds,  exactly  as  passed to the poll(2) system
36               call.
37
38       timeout The original timeout, exactly as passed to the  poll(2)  system
39               call.
40
41       Returns:
42               The message explaining the error. This message buffer is shared
43               by all libexplain functions which do not  supply  a  buffer  in
44               their argument list.  This will be overwritten by the next call
45               to any libexplain function which shares this buffer,  including
46               other threads.
47
48       Note: This function is not thread safe, because it shares a return buf‐
49       fer across all threads, and many other functions in this library.
50
51       Example: This function is intended to be used in a fashion  similar  to
52       the following example:
53              int result = poll(fds, nfds, timeout);
54              if (result < 0)
55              {
56                  fprintf(stderr, "%s\n", explain_poll(fds, nfds, timeout));
57                  exit(EXIT_FAILURE);
58              }
59
60       The   above   code   example   is   available   pre-packaged   as   the
61       explain_poll_or_die(3) function.
62
63   explain_errno_poll
64       const char *explain_errno_poll(int errnum, struct pollfd *fds, int
65       nfds, int timeout);
66
67       The  explain_errno_poll function is used to obtain an explanation of an
68       error returned by the poll(2) system call. The least the  message  will
69       contain  is  the  value of strerror(errno), but usually it will do much
70       better, and indicate the underlying cause in more detail.
71
72       errnum  The error value to be decoded, usually obtained from the  errno
73               global  variable  just  before this function is called. This is
74               necessary if you need to call any code between the system  call
75               to  be explained and this function, because many libc functions
76               will alter the value of errno.
77
78       fds     The original fds, exactly as passed to the poll(2) system call.
79
80       nfds    The original nfds, exactly as  passed  to  the  poll(2)  system
81               call.
82
83       timeout The  original  timeout, exactly as passed to the poll(2) system
84               call.
85
86       Returns:
87               The message explaining the error. This message buffer is shared
88               by  all  libexplain  functions  which do not supply a buffer in
89               their argument list.  This will be overwritten by the next call
90               to  any libexplain function which shares this buffer, including
91               other threads.
92
93       Note: This function is not thread safe, because it shares a return buf‐
94       fer across all threads, and many other functions in this library.
95
96       Example:  This  function is intended to be used in a fashion similar to
97       the following example:
98              int result = poll(fds, nfds, timeout);
99              if (result < 0)
100              {
101                  int err = errno;
102                  fprintf(stderr, "%s\n", explain_errno_poll(err, fds, nfds,
103                  timeout));
104                  exit(EXIT_FAILURE);
105              }
106
107       The   above   code   example   is   available   pre-packaged   as   the
108       explain_poll_or_die(3) function.
109
110   explain_message_poll
111       void explain_message_poll(char *message, int message_size, struct
112       pollfd *fds, int nfds, int timeout);
113
114       The  explain_message_poll  function is used to obtain an explanation of
115       an error returned by the poll(2) system call.  The  least  the  message
116       will  contain  is  the value of strerror(errno), but usually it will do
117       much better, and indicate the underlying cause in more detail.
118
119       The errno global variable will be used to obtain the error value to  be
120       decoded.
121
122       message The location in which to store the returned message. If a suit‐
123               able message return buffer is supplied, this function is thread
124               safe.
125
126       message_size
127               The  size  in  bytes  of  the  location  in  which to store the
128               returned message.
129
130       fds     The original fds, exactly as passed to the poll(2) system call.
131
132       nfds    The original nfds, exactly as  passed  to  the  poll(2)  system
133               call.
134
135       timeout The  original  timeout, exactly as passed to the poll(2) system
136               call.
137
138       Example: This function is intended to be used in a fashion  similar  to
139       the following example:
140              int result = poll(fds, nfds, timeout);
141              if (result < 0)
142              {
143                  char message[3000];
144                  explain_message_poll(message, sizeof(message), fds, nfds,
145                  timeout);
146                  fprintf(stderr, "%s\n", message);
147                  exit(EXIT_FAILURE);
148              }
149
150       The   above   code   example   is   available   pre-packaged   as   the
151       explain_poll_or_die(3) function.
152
153   explain_message_errno_poll
154       void explain_message_errno_poll(char *message, int message_size, int
155       errnum, struct pollfd *fds, int nfds, int timeout);
156
157       The explain_message_errno_poll function is used to obtain  an  explana‐
158       tion  of  an  error  returned by the poll(2) system call. The least the
159       message will contain is the value of strerror(errno),  but  usually  it
160       will do much better, and indicate the underlying cause in more detail.
161
162       message The location in which to store the returned message. If a suit‐
163               able message return buffer is supplied, this function is thread
164               safe.
165
166       message_size
167               The  size  in  bytes  of  the  location  in  which to store the
168               returned message.
169
170       errnum  The error value to be decoded, usually obtained from the  errno
171               global  variable  just  before this function is called. This is
172               necessary if you need to call any code between the system  call
173               to  be explained and this function, because many libc functions
174               will alter the value of errno.
175
176       fds     The original fds, exactly as passed to the poll(2) system call.
177
178       nfds    The original nfds, exactly as  passed  to  the  poll(2)  system
179               call.
180
181       timeout The  original  timeout, exactly as passed to the poll(2) system
182               call.
183
184       Example: This function is intended to be used in a fashion  similar  to
185       the following example:
186              int result = poll(fds, nfds, timeout);
187              if (result < 0)
188              {
189                  int err = errno;
190                  char message[3000];
191                  explain_message_errno_poll(message, sizeof(message), err,
192                  fds, nfds, timeout);
193                  fprintf(stderr, "%s\n", message);
194                  exit(EXIT_FAILURE);
195              }
196
197       The   above   code   example   is   available   pre-packaged   as   the
198       explain_poll_or_die(3) function.
199

SEE ALSO

201       poll(2) wait for some event on a file descriptor
202
203       explain_poll_or_die(3)
204               wait for some event on a file descriptor and report errors
205
207       libexplain version 0.40
208       Copyright (C) 2010 Peter Miller
209
210
211
212                                                               explain_poll(3)
Impressum