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

NAME

6       explain_getsockopt - explain getsockopt(2) errors
7

SYNOPSIS

9       #include <libexplain/getsockopt.h>
10       const  char  *explain_getsockopt(int  fildes, int level, int name, void
11       *data, socklen_t *data_size);
12       const char *explain_errno_getsockopt(int errnum, int fildes, int level,
13       int name, void *data, socklen_t *data_size);
14       void  explain_message_getsockopt(char  *message,  int message_size, int
15       fildes, int level, int name, void *data, socklen_t *data_size);
16       void explain_message_errno_getsockopt(char *message, int  message_size,
17       int  errnum,  int  fildes,  int  level, int name, void *data, socklen_t
18       *data_size);
19

DESCRIPTION

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

SEE ALSO

236       getsockopt(2)
237               get and set options on sockets
238
239       explain_getsockopt_or_die(3)
240               get and set options on sockets and report errors
241
243       libexplain version 0.40
244       Copyright (C) 2009 Peter Miller
245
246
247
248                                                         explain_getsockopt(3)
Impressum