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

NAME

6       explain_ioctl - explain ioctl(2) errors
7

SYNOPSIS

9       #include <libexplain/ioctl.h>
10       const char *explain_ioctl(int fildes, int request, void *data);
11       const  char  *explain_errno_ioctl(int  errnum, int fildes, int request,
12       void *data);
13       void explain_message_ioctl(char *message, int message_size, int fildes,
14       int request, void *data);
15       void  explain_message_errno_ioctl(char  *message, int message_size, int
16       errnum, int fildes, int request, void *data);
17

DESCRIPTION

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

SEE ALSO

202       ioctl(2)
203               control device
204
205       explain_ioctl_or_die(3)
206               control device and report errors
207
209       libexplain version 0.40
210       Copyright (C) 2008 Peter Miller
211
212
213
214                                                              explain_ioctl(3)
Impressum