1explain_socket(3) Library Functions Manual explain_socket(3)
2
6 explain_socket - explain socket(2) errors
7
9 #include <libexplain/socket.h>
10 const char *explain_socket(int domain, int type, int protocol);
11 const char *explain_errno_socket(int errnum, int domain, int type, int
12 protocol);
13 void explain_message_socket(char *message, int message_size, int
14 domain, int type, int protocol);
15 void explain_message_errno_socket(char *message, int message_size, int
16 errnum, int domain, int type, int protocol);
17
19 These functions may be used to obtain explanations for errors returned
20 by the socket(2) system call.
21 explain_socket
23 const char *explain_socket(int domain, int type, int protocol);
24 The explain_socket function is used to obtain an explanation of an
26 error returned by the socket(2) system call. The least the message
27 will contain is the value of strerror(errno), but usually it will do
28 much better, and indicate the underlying cause in more detail.
29 The errno global variable will be used to obtain the error value to be
31 decoded.
32 This function is intended to be used in a fashion similar to the fol‐
34 lowing example:
35 if (socket(domain, type, protocol) < 0)
36 {
37 fprintf(stderr, "%s\n", explain_socket(domain, type, protocol));
38 exit(EXIT_FAILURE);
39 }
40 domain The original domain, exactly as passed to the socket(2) system
42 call.
43 type The original type, exactly as passed to the socket(2) system
45 call.
46 protocol
48 The original protocol, exactly as passed to the socket(2) sys‐
49 tem call.
50 Returns:
52 The message explaining the error. This message buffer is
53 shared by all libexplain functions which do not supply a buffer
54 in their argument list. This will be overwritten by the next
55 call to any libexplain function which shares this buffer,
56 including other threads.
57 Note: This function is not thread safe, because it shares a return buf‐
59 fer across all threads, and many other functions in this library.
60 explain_errno_socket
62 const char *explain_errno_socket(int errnum, int domain, int type, int
63 protocol);
64 The explain_errno_socket function is used to obtain an explanation of
66 an error returned by the socket(2) system call. The least the message
67 will contain is the value of strerror(errnum), but usually it will do
68 much better, and indicate the underlying cause in more detail.
69 This function is intended to be used in a fashion similar to the fol‐
71 lowing example:
72 if (socket(domain, type, protocol) < 0)
73 {
74 int err = errno;
75 fprintf(stderr, "%s\n", explain_errno_socket(err,
76 domain, type, protocol));
77 exit(EXIT_FAILURE);
78 }
79 errnum The error value to be decoded, usually obtained from the errno
81 global variable just before this function is called. This is
82 necessary if you need to call any code between the system call
83 to be explained and this function, because many libc functions
84 will alter the value of errno.
85 domain The original domain, exactly as passed to the socket(2) system
87 call.
88 type The original type, exactly as passed to the socket(2) system
90 call.
91 protocol
93 The original protocol, exactly as passed to the socket(2) sys‐
94 tem call.
95 Returns:
97 The message explaining the error. This message buffer is
98 shared by all libexplain functions which do not supply a buffer
99 in their argument list. This will be overwritten by the next
100 call to any libexplain function which shares this buffer,
101 including other threads.
102 Note: This function is not thread safe, because it shares a return buf‐
104 fer across all threads, and many other functions in this library.
105 explain_message_socket
107 void explain_message_socket(char *message, int message_size, int
108 domain, int type, int protocol);
109 The explain_message_socket function may be used to obtain an explana‐
111 tion of an error returned by the socket(2) system call. The least the
112 message will contain is the value of strerror(errno), but usually it
113 will do much better, and indicate the underlying cause in more detail.
114 The errno global variable will be used to obtain the error value to be
116 decoded.
117 This function is intended to be used in a fashion similar to the fol‐
119 lowing example:
120 if (socket(domain, type, protocol) < 0)
121 {
122 char message[3000];
123 explain_message_socket(message, sizeof(message), domain, type, protocol);
124 fprintf(stderr, "%s\n", message);
125 exit(EXIT_FAILURE);
126 }
127 message The location in which to store the returned message. If a
129 suitable message return buffer is supplied, this function is
130 thread safe.
131 message_size
133 The size in bytes of the location in which to store the
134 returned message.
135 domain The original domain, exactly as passed to the socket(2) system
137 call.
138 type The original type, exactly as passed to the socket(2) system
140 call.
141 protocol
143 The original protocol, exactly as passed to the socket(2) sys‐
144 tem call.
145 explain_message_errno_socket
147 void explain_message_errno_socket(char *message, int message_size, int
148 errnum, int domain, int type, int protocol);
149 The explain_message_errno_socket function may be used to obtain an
151 explanation of an error returned by the socket(2) system call. The
152 least the message will contain is the value of strerror(errnum), but
153 usually it will do much better, and indicate the underlying cause in
154 more detail.
155 This function is intended to be used in a fashion similar to the fol‐
157 lowing example:
158 if (socket(domain, type, protocol) < 0)
159 {
160 int err = errno;
161 char message[3000];
162 explain_message_errno_socket(message, sizeof(message), err,
163 domain, type, protocol);
164 fprintf(stderr, "%s\n", message);
165 exit(EXIT_FAILURE);
166 }
167 message The location in which to store the returned message. If a
169 suitable message return buffer is supplied, this function is
170 thread safe.
171 message_size
173 The size in bytes of the location in which to store the
174 returned message.
175 errnum The error value to be decoded, usually obtained from the errno
177 global variable just before this function is called. This is
178 necessary if you need to call any code between the system call
179 to be explained and this function, because many libc functions
180 will alter the value of errno.
181 domain The original domain, exactly as passed to the socket(2) system
183 call.
184 type The original type, exactly as passed to the socket(2) system
186 call.
187 protocol
189 The original protocol, exactly as passed to the socket(2) sys‐
190 tem call.
191
193 socket(2)
194 create an endpoint for communication
195 explain_socket_or_die(3)
197 create an endpoint for communication and report errors
198
200 libexplain version 1.4
201 Copyright (C) 2008 Peter Miller
202 explain_socket(3)