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

NAME

6       explain_bind - explain bind(2) errors
7

SYNOPSIS

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

DESCRIPTION

21       These functions may be used to obtain explanations for errors  returned
22       by the bind(2) system call.
23
24   explain_bind
25       const  char *explain_bind(int fildes, const struct sockaddr *sock_addr,
26       int sock_addr_size);
27
28       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
33       The  errno global variable will be used to obtain the error value to be
34       decoded.
35
36       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
45       The   above   code   example   is   available   pre‐packaged   as   the
46       explain_bind_or_die(3) function.
47
48       fildes  The original fildes, exactly as passed to  the  bind(2)  system
49               call.
50
51       sock_addr
52               The original sock_addr, exactly as passed to the bind(2) system
53               call.
54
55       sock_addr_size
56               The original sock_addr_size, exactly as passed to  the  bind(2)
57               system call.
58
59       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
66       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
69   explain_errno_bind
70       const char *explain_errno_bind(int errnum,  int  fildes,  const  struct
71       sockaddr *sock_addr, int sock_addr_size);
72
73       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
78       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
88       The   above   code   example   is   available   pre‐packaged   as   the
89       explain_bind_or_die(3) function.
90
91       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
97       fildes  The original fildes, exactly as passed to  the  bind(2)  system
98               call.
99
100       sock_addr
101               The original sock_addr, exactly as passed to the bind(2) system
102               call.
103
104       sock_addr_size
105               The original sock_addr_size, exactly as passed to  the  bind(2)
106               system call.
107
108       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
115       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
118   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
122       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
127       The errno global variable will be used to obtain the error value to  be
128       decoded.
129
130       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
141       The   above   code   example   is   available   pre‐packaged   as   the
142       explain_bind_or_die(3) function.
143
144       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
148       message_size
149               The  size  in  bytes  of  the  location  in  which to store the
150               returned message.
151
152       fildes  The original fildes, exactly as passed to  the  bind(2)  system
153               call.
154
155       sock_addr
156               The original sock_addr, exactly as passed to the bind(2) system
157               call.
158
159       sock_addr_size
160               The original sock_addr_size, exactly as passed to  the  bind(2)
161               system call.
162
163   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
168       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
173       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
185       The   above   code   example   is   available   pre‐packaged   as   the
186       explain_bind_or_die(3) function.
187
188       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
192       message_size
193               The size in bytes  of  the  location  in  which  to  store  the
194               returned message.
195
196       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
202       fildes  The  original  fildes,  exactly as passed to the bind(2) system
203               call.
204
205       sock_addr
206               The original sock_addr, exactly as passed to the bind(2) system
207               call.
208
209       sock_addr_size
210               The  original  sock_addr_size, exactly as passed to the bind(2)
211               system call.
212

SEE ALSO

214       bind(2) bind a name to a socket
215
216       explain_bind_or_die(3)
217               bind a name to a socket and report errors
218
220       libexplain version 0.40
221       Copyright (C) 2008 Peter Miller
222
223
224
225                                                               explain_bind(3)
Impressum