1explain_fcntl(3) Library Functions Manual explain_fcntl(3)
2
6 explain_fcntl - explain fcntl(2) errors
7
9 #include <libexplain/fcntl.h>
10 const char *explain_fcntl(int fildes, int command, long arg);
11 const char *explain_errno_fcntl(int errnum, int fildes, int command,
12 long arg);
13 void explain_message_fcntl(char *message, int message_size, int fildes,
14 int command, long arg);
15 void explain_message_errno_fcntl(char *message, int message_size, int
16 errnum, int fildes, int command, long arg);
17
19 These functions may be used to obtain explanations for errors returned
20 by the fcntl(2) system call.
21 explain_fcntl
23 const char *explain_fcntl(int fildes, int command, long arg);
24 The explain_fcntl function is used to obtain an explanation of an error
26 returned by the fcntl(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 if (fcntl(fildes, command, arg) < 0)
36 {
37 fprintf(stderr, "%s\n", explain_fcntl(fildes, command, arg));
38 exit(EXIT_FAILURE);
39 }
40 fildes The original fildes, exactly as passed to the fcntl(2) system
42 call.
43 command The original command, exactly as passed to the fcntl(2) system
45 call.
46 arg The original arg, exactly as passed to the fcntl(2) system
48 call.
49 Returns:
51 The message explaining the error. This message buffer is
52 shared by all libexplain functions which do not supply a buffer
53 in their argument list. This will be overwritten by the next
54 call to any libexplain function which shares this buffer,
55 including other threads.
56 Note: This function is not thread safe, because it shares a return buf‐
58 fer across all threads, and many other functions in this library.
59 explain_errno_fcntl
61 const char *explain_errno_fcntl(int errnum, int fildes, int command,
62 long arg);
63 The explain_errno_fcntl function is used to obtain an explanation of an
65 error returned by the fcntl(2) system call. The least the message will
66 contain is the value of strerror(errnum), but usually it will do much
67 better, and indicate the underlying cause in more detail.
68 This function is intended to be used in a fashion similar to the fol‐
70 lowing example:
71 if (fcntl(fildes, command, arg) < 0)
72 {
73 int err = errno;
74 fprintf(stderr, "%s\n", explain_errno_fcntl(err, fildes, command, arg));
75 exit(EXIT_FAILURE);
76 }
77 errnum The error value to be decoded, usually obtained from the errno
79 global variable just before this function is called. This is
80 necessary if you need to call any code between the system call
81 to be explained and this function, because many libc functions
82 will alter the value of errno.
83 fildes The original fildes, exactly as passed to the fcntl(2) system
85 call.
86 command The original command, exactly as passed to the fcntl(2) system
88 call.
89 arg The original arg, exactly as passed to the fcntl(2) system
91 call.
92 Returns:
94 The message explaining the error. This message buffer is
95 shared by all libexplain functions which do not supply a buffer
96 in their argument list. This will be overwritten by the next
97 call to any libexplain function which shares this buffer,
98 including other threads.
99 Note: This function is not thread safe, because it shares a return buf‐
101 fer across all threads, and many other functions in this library.
102 explain_message_fcntl
104 void explain_message_fcntl(char *message, int message_size, int fildes,
105 int command, long arg);
106 The explain_message_fcntl function may be used to obtain an explana‐
108 tion of an error returned by the fcntl(2) system call. The least the
109 message will contain is the value of strerror(errno), but usually it
110 will do much better, and indicate the underlying cause in more detail.
111 The errno global variable will be used to obtain the error value to be
113 decoded.
114 This function is intended to be used in a fashion similar to the fol‐
116 lowing example:
117 if (fcntl(fildes, command, arg) < 0)
118 {
119 char message[3000];
120 explain_message_fcntl(message, sizeof(message), fildes, command, arg);
121 fprintf(stderr, "%s\n", message);
122 exit(EXIT_FAILURE);
123 }
124 message The location in which to store the returned message. If a
126 suitable message return buffer is supplied, this function is
127 thread safe.
128 message_size
130 The size in bytes of the location in which to store the
131 returned message.
132 fildes The original fildes, exactly as passed to the fcntl(2) system
134 call.
135 command The original command, exactly as passed to the fcntl(2) system
137 call.
138 arg The original arg, exactly as passed to the fcntl(2) system
140 call.
141 explain_message_errno_fcntl
143 void explain_message_errno_fcntl(char *message, int message_size, int
144 errnum, int fildes, int command, long arg);
145 The explain_message_errno_fcntl function may be used to obtain an
147 explanation of an error returned by the fcntl(2) system call. The
148 least the message will contain is the value of strerror(errnum), but
149 usually it will do much better, and indicate the underlying cause in
150 more detail.
151 This function is intended to be used in a fashion similar to the fol‐
153 lowing example:
154 if (fcntl(fildes, command, arg) < 0)
155 {
156 int err = errno;
157 char message[3000];
158 explain_message_errno_fcntl(message, sizeof(message), err, fildes,
159 command, arg);
160 fprintf(stderr, "%s\n", message);
161 exit(EXIT_FAILURE);
162 }
163 message The location in which to store the returned message. If a
165 suitable message return buffer is supplied, this function is
166 thread safe.
167 message_size
169 The size in bytes of the location in which to store the
170 returned message.
171 errnum The error value to be decoded, usually obtained from the errno
173 global variable just before this function is called. This is
174 necessary if you need to call any code between the system call
175 to be explained and this function, because many libc functions
176 will alter the value of errno.
177 fildes The original fildes, exactly as passed to the fcntl(2) system
179 call.
180 command The original command, exactly as passed to the fcntl(2) system
182 call.
183 arg The original arg, exactly as passed to the fcntl(2) system
185 call.
186
188 fcntl(2)
189 manipulate a file descriptor
190 explain_fcntl_or_die(3)
192 manipulate a file descriptor and report errors
193
195 libexplain version 1.4
196 Copyright (C) 2008 Peter Miller
197 explain_fcntl(3)