1explain_socketpair(3) Library Functions Manual explain_socketpair(3)
2
6 explain_socketpair - explain socketpair(2) errors
7
9 #include <libexplain/socketpair.h>
10 const char *explain_socketpair(int domain, int type, int protocol, int
11 *sv);
12 const char *explain_errno_socketpair(int errnum, int domain, int type,
13 int protocol, int *sv);
14 void explain_message_socketpair(char *message, int message_size, int
15 domain, int type, int protocol, int *sv);
16 void explain_message_errno_socketpair(char *message, int message_size,
17 int errnum, int domain, int type, int protocol, int *sv);
18
20 These functions may be used to obtain explanations for errors returned
21 by the socketpair(2) system call.
22 explain_socketpair
24 const char *explain_socketpair(int domain, int type, int protocol, int
25 *sv);
26 The explain_socketpair function is used to obtain an explanation of an
28 error returned by the socketpair(2) system call. The least the message
29 will contain is the value of strerror(errno), but usually it will do
30 much better, and indicate the underlying cause in more detail.
31 The errno global variable will be used to obtain the error value to be
33 decoded.
34 domain The original domain, exactly as passed to the socketpair(2)
36 system call.
37 type The original type, exactly as passed to the socketpair(2) sys‐
39 tem call.
40 protocol
42 The original protocol, exactly as passed to the socketpair(2)
43 system call.
44 sv The original sv, exactly as passed to the socketpair(2) system
46 call.
47 Returns:
49 The message explaining the error. This message buffer is shared
50 by all libexplain functions which do not supply a buffer in
51 their argument list. This will be overwritten by the next call
52 to any libexplain function which shares this buffer, including
53 other threads.
54 Note: This function is not thread safe, because it shares a return buf‐
56 fer across all threads, and many other functions in this library.
57 Example: This function is intended to be used in a fashion similar to
59 the following example:
60 if (socketpair(domain, type, protocol, sv) < 0)
61 {
62 fprintf(stderr, "%s\n", explain_socketpair(domain, type,
63 protocol, sv));
64 exit(EXIT_FAILURE);
65 }
66 The above code example is available pre‐packaged as the explain_socket‐
68 pair_or_die(3) function.
69 explain_errno_socketpair
71 const char *explain_errno_socketpair(int errnum, int domain, int type,
72 int protocol, int *sv);
73 The explain_errno_socketpair function is used to obtain an explanation
75 of an error returned by the socketpair(2) system call. The least the
76 message will contain is the value of strerror(errno), but usually it
77 will do much better, and indicate the underlying cause in more detail.
78 errnum The error value to be decoded, usually obtained from the errno
80 global variable just before this function is called. This is
81 necessary if you need to call any code between the system call
82 to be explained and this function, because many libc functions
83 will alter the value of errno.
84 domain The original domain, exactly as passed to the socketpair(2)
86 system call.
87 type The original type, exactly as passed to the socketpair(2) sys‐
89 tem call.
90 protocol
92 The original protocol, exactly as passed to the socketpair(2)
93 system call.
94 sv The original sv, exactly as passed to the socketpair(2) system
96 call.
97 Returns:
99 The message explaining the error. This message buffer is shared
100 by all libexplain functions which do not supply a buffer in
101 their argument list. This will be overwritten by the next call
102 to any libexplain function which shares this buffer, including
103 other threads.
104 Note: This function is not thread safe, because it shares a return buf‐
106 fer across all threads, and many other functions in this library.
107 Example: This function is intended to be used in a fashion similar to
109 the following example:
110 if (socketpair(domain, type, protocol, sv) < 0)
111 {
112 int err = errno;
113 fprintf(stderr, "%s\n", explain_errno_socketpair(err,
114 domain, type, protocol, sv));
115 exit(EXIT_FAILURE);
116 }
117 The above code example is available pre‐packaged as the explain_socket‐
119 pair_or_die(3) function.
120 explain_message_socketpair
122 void explain_message_socketpair(char *message, int message_size, int
123 domain, int type, int protocol, int *sv);
124 The explain_message_socketpair function is used to obtain an explana‐
126 tion of an error returned by the socketpair(2) system call. The least
127 the message will contain is the value of strerror(errno), but usually
128 it will do much better, and indicate the underlying cause in more
129 detail.
130 The errno global variable will be used to obtain the error value to be
132 decoded.
133 message The location in which to store the returned message. If a suit‐
135 able message return buffer is supplied, this function is thread
136 safe.
137 message_size
139 The size in bytes of the location in which to store the
140 returned message.
141 domain The original domain, exactly as passed to the socketpair(2)
143 system call.
144 type The original type, exactly as passed to the socketpair(2) sys‐
146 tem call.
147 protocol
149 The original protocol, exactly as passed to the socketpair(2)
150 system call.
151 sv The original sv, exactly as passed to the socketpair(2) system
153 call.
154 Example: This function is intended to be used in a fashion similar to
156 the following example:
157 if (socketpair(domain, type, protocol, sv) < 0)
158 {
159 char message[3000];
160 explain_message_socketpair(message, sizeof(message), domain,
161 type, protocol, sv);
162 fprintf(stderr, "%s\n", message);
163 exit(EXIT_FAILURE);
164 }
165 The above code example is available pre‐packaged as the explain_socket‐
167 pair_or_die(3) function.
168 explain_message_errno_socketpair
170 void explain_message_errno_socketpair(char *message, int message_size,
171 int errnum, int domain, int type, int protocol, int *sv);
172 The explain_message_errno_socketpair function is used to obtain an
174 explanation of an error returned by the socketpair(2) system call. The
175 least the message will contain is the value of strerror(errno), but
176 usually it will do much better, and indicate the underlying cause in
177 more detail.
178 message The location in which to store the returned message. If a suit‐
180 able message return buffer is supplied, this function is thread
181 safe.
182 message_size
184 The size in bytes of the location in which to store the
185 returned message.
186 errnum The error value to be decoded, usually obtained from the errno
188 global variable just before this function is called. This is
189 necessary if you need to call any code between the system call
190 to be explained and this function, because many libc functions
191 will alter the value of errno.
192 domain The original domain, exactly as passed to the socketpair(2)
194 system call.
195 type The original type, exactly as passed to the socketpair(2) sys‐
197 tem call.
198 protocol
200 The original protocol, exactly as passed to the socketpair(2)
201 system call.
202 sv The original sv, exactly as passed to the socketpair(2) system
204 call.
205 Example: This function is intended to be used in a fashion similar to
207 the following example:
208 if (socketpair(domain, type, protocol, sv) < 0)
209 {
210 int err = errno;
211 char message[3000];
212 explain_message_errno_socketpair(message, sizeof(message),
213 err, domain, type, protocol, sv);
214 fprintf(stderr, "%s\n", message);
215 exit(EXIT_FAILURE);
216 }
217 The above code example is available pre‐packaged as the explain_socket‐
219 pair_or_die(3) function.
220
222 socketpair(2)
223 create a pair of connected sockets
224 explain_socketpair_or_die(3)
226 create a pair of connected sockets and report errors
227
229 libexplain version 0.40
230 Copyright (C) 2010 Peter Miller
231 explain_socketpair(3)