1explain_ioctl(3) Library Functions Manual explain_ioctl(3)
2
6 explain_ioctl - explain ioctl(2) errors
7
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
19 These functions may be used to obtain explanations for errors returned
20 by the ioctl(2) system call.
21 explain_ioctl
23 const char *explain_ioctl(int fildes, int request, void *data);
24 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 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 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 The above code example is available pre‐packaged as the
43 explain_ioctl_or_die(3) function.
44 fildes The original fildes, exactly as passed to the ioctl(2) system
46 call.
47 request The original request, exactly as passed to the ioctl(2) system
49 call.
50 data The original data, exactly as passed to the ioctl(2) system
52 call.
53 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 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 explain_errno_ioctl
65 const char *explain_errno_ioctl(int errnum, int fildes, int request,
66 void *data);
67 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 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 The above code example is available pre‐packaged as the
84 explain_ioctl_or_die(3) function.
85 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 fildes The original fildes, exactly as passed to the ioctl(2) system
93 call.
94 request The original request, exactly as passed to the ioctl(2) system
96 call.
97 data The original data, exactly as passed to the ioctl(2) system
99 call.
100 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 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 explain_message_ioctl
112 void explain_message_ioctl(char *message, int message_size, int fildes,
113 int request, void *data);
114 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 The errno global variable will be used to obtain the error value to be
121 decoded.
122 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 The above code example is available pre‐packaged as the
134 explain_ioctl_or_die(3) function.
135 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 message_size
141 The size in bytes of the location in which to store the
142 returned message.
143 fildes The original fildes, exactly as passed to the ioctl(2) system
145 call.
146 request The original request, exactly as passed to the ioctl(2) system
148 call.
149 data The original data, exactly as passed to the ioctl(2) system
151 call.
152 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 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 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 The above code example is available pre‐packaged as the
176 explain_ioctl_or_die(3) function.
177 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 message_size
183 The size in bytes of the location in which to store the
184 returned message.
185 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 fildes The original fildes, exactly as passed to the ioctl(2) system
193 call.
194 request The original request, exactly as passed to the ioctl(2) system
196 call.
197 data The original data, exactly as passed to the ioctl(2) system
199 call.
200
202 ioctl(2)
203 control device
204 explain_ioctl_or_die(3)
206 control device and report errors
207
209 libexplain version 1.4
210 Copyright (C) 2008 Peter Miller
211 explain_ioctl(3)