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

NAME

6       explain_listen - explain listen(2) errors
7

SYNOPSIS

9       #include <libexplain/listen.h>
10       const char *explain_listen(int fildes, int backlog);
11       const char *explain_errno_listen(int errnum, int fildes, int backlog);
12       void   explain_message_listen(char   *message,  int  message_size,  int
13       fildes, int backlog);
14       void explain_message_errno_listen(char *message, int message_size,  int
15       errnum, int fildes, int backlog);
16

DESCRIPTION

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

SEE ALSO

186       listen(2)
187               listen for connections on a socket
188
189       explain_listen_or_die(3)
190               listen for connections on a socket and report errors
191
193       libexplain version 0.40
194       Copyright (C) 2008 Peter Miller
195
196
197
198                                                             explain_listen(3)
Impressum