1explain_connect(3) Library Functions Manual explain_connect(3)
2
6 explain_connect - explain connect(2) errors
7
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
21 These functions may be used to obtain explanations for errors returned
22 by the connect(2) system call.
23 explain_connect
25 const char *explain_connect(int fildes, const struct sockaddr
26 *serv_addr, int serv_addr_size);
27 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 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 (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 fildes The original fildes, exactly as passed to the connect(2) system
46 call.
47 serv_addr
49 The original serv_addr, exactly as passed to the connect(2)
50 system call.
51 serv_addr_size
53 The original serv_addr_size, exactly as passed to the con‐
54 nect(2) system call.
55 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 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 explain_errno_connect
67 const char *explain_errno_connect(int errnum, int fildes, const struct
68 sockaddr *serv_addr, int serv_addr_size);
69 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 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 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 fildes The original fildes, exactly as passed to the connect(2) system
92 call.
93 serv_addr
95 The original serv_addr, exactly as passed to the connect(2)
96 system call.
97 serv_addr_size
99 The original serv_addr_size, exactly as passed to the con‐
100 nect(2) system call.
101 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 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 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 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 The errno global variable will be used to obtain the error value to be
122 decoded.
123 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 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 message_size
140 The size in bytes of the location in which to store the
141 returned message.
142 fildes The original fildes, exactly as passed to the connect(2) system
144 call.
145 serv_addr
147 The original serv_addr, exactly as passed to the connect(2)
148 system call.
149 serv_addr_size
151 The original serv_addr_size, exactly as passed to the con‐
152 nect(2) system call.
153 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 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 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 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 message_size
182 The size in bytes of the location in which to store the
183 returned message.
184 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 fildes The original fildes, exactly as passed to the connect(2) system
192 call.
193 serv_addr
195 The original serv_addr, exactly as passed to the connect(2)
196 system call.
197 serv_addr_size
199 The original serv_addr_size, exactly as passed to the con‐
200 nect(2) system call.
201
203 connect(2)
204 initiate a connection on a socket
205 explain_connect_or_die(3)
207 initiate a connection on a socket and report errors
208
210 libexplain version 1.4
211 Copyright (C) 2008 Peter Miller
212 explain_connect(3)