1explain_listen(3) Library Functions Manual explain_listen(3)
2
6 explain_listen - explain listen(2) errors
7
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
18 These functions may be used to obtain explanations for errors returned
19 by the listen(2) system call.
20 explain_listen
22 const char *explain_listen(int fildes, int backlog);
23 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 The errno global variable will be used to obtain the error value to be
30 decoded.
31 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 The above code example is available pre‐packaged as the explain_lis‐
41 ten_or_die(3) function.
42 fildes The original fildes, exactly as passed to the listen(2) system
44 call.
45 backlog The original backlog, exactly as passed to the listen(2) system
47 call.
48 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 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 explain_errno_listen
60 const char *explain_errno_listen(int errnum, int fildes, int backlog);
61 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 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 The above code example is available pre‐packaged as the explain_lis‐
77 ten_or_die(3) function.
78 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 fildes The original fildes, exactly as passed to the listen(2) system
86 call.
87 backlog The original backlog, exactly as passed to the listen(2) system
89 call.
90 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 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 explain_message_listen
102 void explain_message_listen(char *message, int message_size, int
103 fildes, int backlog);
104 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 The errno global variable will be used to obtain the error value to be
111 decoded.
112 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 The above code example is available pre‐packaged as the explain_lis‐
124 ten_or_die(3) function.
125 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 message_size
131 The size in bytes of the location in which to store the
132 returned message.
133 fildes The original fildes, exactly as passed to the listen(2) system
135 call.
136 backlog The original backlog, exactly as passed to the listen(2) system
138 call.
139 explain_message_errno_listen
141 void explain_message_errno_listen(char *message, int message_size, int
142 errnum, int fildes, int backlog);
143 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 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 The above code example is available pre‐packaged as the explain_lis‐
163 ten_or_die(3) function.
164 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 message_size
170 The size in bytes of the location in which to store the
171 returned message.
172 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 fildes The original fildes, exactly as passed to the listen(2) system
180 call.
181 backlog The original backlog, exactly as passed to the listen(2) system
183 call.
184
186 listen(2)
187 listen for connections on a socket
188 explain_listen_or_die(3)
190 listen for connections on a socket and report errors
191
193 libexplain version 1.4
194 Copyright (C) 2008 Peter Miller
195 explain_listen(3)