1explain_bind(3) Library Functions Manual explain_bind(3)
2
6 explain_bind - explain bind(2) errors
7
9 #include <libexplain/bind.h>
10 const char *explain_bind(int fildes, const struct sockaddr *sock_addr,
11 int sock_addr_size);
12 const char *explain_errno_bind(int errnum, int fildes, const struct
13 sockaddr *sock_addr, int sock_addr_size);
14 void explain_message_bind(char *message, int message_size, int fildes,
15 const struct sockaddr *sock_addr, int sock_addr_size);
16 void explain_message_errno_bind(char *message, int message_size, int
17 errnum, int fildes, const struct sockaddr *sock_addr, int
18 sock_addr_size);
19
21 These functions may be used to obtain explanations for errors returned
22 by the bind(2) system call.
23 explain_bind
25 const char *explain_bind(int fildes, const struct sockaddr *sock_addr,
26 int sock_addr_size);
27 The explain_bind function is used to obtain an explanation of an error
29 returned by the bind(2) system call. The least the message will con‐
30 tain is the value of strerror(errno), but usually it will do much bet‐
31 ter, and indicate the underlying cause in more detail.
32 The errno global variable will be used to obtain the error value to be
34 decoded.
35 This function is intended to be used in a fashion similar to the fol‐
37 lowing example:
38 if (bind(fildes, sock_addr, sock_addr_size) < 0)
39 {
40 fprintf(stderr, "%s\n",
41 explain_bind(fildes, sock_addr, sock_addr_size));
42 exit(EXIT_FAILURE);
43 }
44 The above code example is available pre‐packaged as the
46 explain_bind_or_die(3) function.
47 fildes The original fildes, exactly as passed to the bind(2) system
49 call.
50 sock_addr
52 The original sock_addr, exactly as passed to the bind(2) system
53 call.
54 sock_addr_size
56 The original sock_addr_size, exactly as passed to the bind(2)
57 system call.
58 Returns:
60 The message explaining the error. This message buffer is
61 shared by all libexplain functions which do not supply a buffer
62 in their argument list. This will be overwritten by the next
63 call to any libexplain function which shares this buffer,
64 including other threads.
65 Note: This function is not thread safe, because it shares a return buf‐
67 fer across all threads, and many other functions in this library.
68 explain_errno_bind
70 const char *explain_errno_bind(int errnum, int fildes, const struct
71 sockaddr *sock_addr, int sock_addr_size);
72 The explain_errno_bind function is used to obtain an explanation of an
74 error returned by the bind(2) system call. The least the message will
75 contain is the value of strerror(errnum), but usually it will do much
76 better, and indicate the underlying cause in more detail.
77 This function is intended to be used in a fashion similar to the fol‐
79 lowing example:
80 if (bind(fildes, sock_addr, sock_addr_size) < 0)
81 {
82 int err = errno;
83 fprintf(stderr, "%s\n", explain_errno_bind(err,
84 fildes, sock_addr, sock_addr_size));
85 exit(EXIT_FAILURE);
86 }
87 The above code example is available pre‐packaged as the
89 explain_bind_or_die(3) function.
90 errnum The error value to be decoded, usually obtained from the errno
92 global variable just before this function is called. This is
93 necessary if you need to call any code between the system call
94 to be explained and this function, because many libc functions
95 will alter the value of errno.
96 fildes The original fildes, exactly as passed to the bind(2) system
98 call.
99 sock_addr
101 The original sock_addr, exactly as passed to the bind(2) system
102 call.
103 sock_addr_size
105 The original sock_addr_size, exactly as passed to the bind(2)
106 system call.
107 Returns:
109 The message explaining the error. This message buffer is
110 shared by all libexplain functions which do not supply a buffer
111 in their argument list. This will be overwritten by the next
112 call to any libexplain function which shares this buffer,
113 including other threads.
114 Note: This function is not thread safe, because it shares a return buf‐
116 fer across all threads, and many other functions in this library.
117 explain_message_bind
119 void explain_message_bind(char *message, int message_size, int fildes,
120 const struct sockaddr *sock_addr, int sock_addr_size);
121 The explain_message_bind function may be used to obtain an explanation
123 of an error returned by the bind(2) system call. The least the message
124 will contain is the value of strerror(errno), but usually it will do
125 much better, and indicate the underlying cause in more detail.
126 The errno global variable will be used to obtain the error value to be
128 decoded.
129 This function is intended to be used in a fashion similar to the fol‐
131 lowing example:
132 if (bind(fildes, sock_addr, sock_addr_size) < 0)
133 {
134 char message[3000];
135 explain_message_bind(message, sizeof(message),
136 fildes, sock_addr, sock_addr_size);
137 fprintf(stderr, "%s\n", message);
138 exit(EXIT_FAILURE);
139 }
140 The above code example is available pre‐packaged as the
142 explain_bind_or_die(3) function.
143 message The location in which to store the returned message. If a
145 suitable message return buffer is supplied, this function is
146 thread safe.
147 message_size
149 The size in bytes of the location in which to store the
150 returned message.
151 fildes The original fildes, exactly as passed to the bind(2) system
153 call.
154 sock_addr
156 The original sock_addr, exactly as passed to the bind(2) system
157 call.
158 sock_addr_size
160 The original sock_addr_size, exactly as passed to the bind(2)
161 system call.
162 explain_message_errno_bind
164 void explain_message_errno_bind(char *message, int message_size, int
165 errnum, int fildes, const struct sockaddr *sock_addr, int
166 sock_addr_size);
167 The explain_message_errno_bind function may be used to obtain an expla‐
169 nation of an error returned by the bind(2) system call. The least the
170 message will contain is the value of strerror(errnum), but usually it
171 will do much better, and indicate the underlying cause in more detail.
172 This function is intended to be used in a fashion similar to the fol‐
174 lowing example:
175 if (bind(fildes, sock_addr, sock_addr_size) < 0)
176 {
177 int err = errno;
178 char message[3000];
179 explain_message_errno_bind(message, sizeof(message), err,
180 fildes, sock_addr, sock_addr_size);
181 fprintf(stderr, "%s\n", message);
182 exit(EXIT_FAILURE);
183 }
184 The above code example is available pre‐packaged as the
186 explain_bind_or_die(3) function.
187 message The location in which to store the returned message. If a
189 suitable message return buffer is supplied, this function is
190 thread safe.
191 message_size
193 The size in bytes of the location in which to store the
194 returned message.
195 errnum The error value to be decoded, usually obtained from the errno
197 global variable just before this function is called. This is
198 necessary if you need to call any code between the system call
199 to be explained and this function, because many libc functions
200 will alter the value of errno.
201 fildes The original fildes, exactly as passed to the bind(2) system
203 call.
204 sock_addr
206 The original sock_addr, exactly as passed to the bind(2) system
207 call.
208 sock_addr_size
210 The original sock_addr_size, exactly as passed to the bind(2)
211 system call.
212
214 bind(2) bind a name to a socket
215 explain_bind_or_die(3)
217 bind a name to a socket and report errors
218
220 libexplain version 1.4
221 Copyright (C) 2008 Peter Miller
222 explain_bind(3)