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

NAME

6       explain_connect - explain connect(2) errors
7

SYNOPSIS

9       #include <libexplain/connect.h>
10       const   char   *explain_connect(int   fildes,   const  struct  sockaddr
11       *serv_addr, int serv_addr_size);
12       const char *explain_errno_connect(int errnum, int fildes, const  struct
13       sockaddr *serv_addr, int serv_addr_size);
14       void   explain_message_connect(char  *message,  int  message_size,  int
15       fildes, const struct sockaddr *serv_addr, int serv_addr_size);
16       void explain_message_errno_connect(char *message, int message_size, int
17       errnum,   int   fildes,   const   struct   sockaddr   *serv_addr,   int
18       serv_addr_size);
19

DESCRIPTION

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

SEE ALSO

203       connect(2)
204               initiate a connection on a socket
205
206       explain_connect_or_die(3)
207               initiate a connection on a socket and report errors
208
210       libexplain version 0.40
211       Copyright (C) 2008 Peter Miller
212
213
214
215                                                            explain_connect(3)
Impressum