1explain_lseek(3) Library Functions Manual explain_lseek(3)
2
6 explain_lseek - explain lseek(2) errors
7
9 #include <libexplain/lseek.h>
10 const char *explain_lseek(int fildes, long long offset, int whence);
11 const char *explain_errno_lseek(int errnum, int fildes, long long off‐
12 set, int whence);
13 void explain_message_lseek(char *message, int message_size, int fildes,
14 long long offset, int whence);
15 void explain_message_errno_lseek(char *message, int message_size, int
16 errnum, int fildes, long long offset, int whence);
17
19 These functions may be used to obtain explanations for lseek(2) errors.
20 explain_lseek
22 const char *explain_lseek(int fildes, long long offset, int whence);
23 The explain_lseek function may be used to obtain a human readable
25 explanation of what went wrong in an lseek(2) system call. The least
26 the message will contain is the value of strerror(errno), but usually
27 it will do much better, and indicate the underlying cause in more
28 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 (lseek(fd, offset, whence) == (off_t)-1)
36 {
37 fprintf(stderr, '%s0, explain_lseek(fd, offset, whence);
38 exit(EXIT_FAILURE);
39 }
40 fildes The original fildes, exactly as passed to the lseek(2) system
42 call.
43 offset The original offset, exactly as passed to the lseek(2) system
45 call.
46 whence The original whence, exactly as passed to the lseek(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_lseek
61 const char *explain_errno_lseek(int errnum, int fildes, long long off‐
62 set, int whence);
63 The explain_errno_lseek function may be used to obtain a human readable
65 explanation of what went wrong in an lseek(2) system call. The least
66 the message will contain is the value of strerror(errnum), but usually
67 it will do much better, and indicate the underlying cause in more
68 detail.
69 This function is intended to be used in a fashion similar to the fol‐
71 lowing example:
72 if (lseek(fd, offset, whence) == (off_t)-1)
73 {
74 int errnum = errno;
75 fprintf(stderr, '%s0, explain_errno_lseek(fd, eernum, offset,
76 whence);
77 exit(EXIT_FAILURE);
78 }
79 errnum The error value to be decoded, usually obtained from the errno
81 global variable just before this function is called. This is
82 necessary if you need to call any code between the system call
83 to be explained and this function, because many libc functions
84 will alter the value of errno.
85 fildes The original fildes, exactly as passed to the lseek(2) system
87 call.
88 offset The original offset, exactly as passed to the lseek(2)
89 system call.
90 whence The original whence, exactly as passed to the lseek(2)
91 system 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_lseek
104 void explain_message_lseek(char *message, int message_size, int fildes,
105 long long offset, int whence);
106 The explain_message_lseek function may be used to obtain a human read‐
108 able explanation of what went wrong in an lseek(2) system call. The
109 least the message will contain is the value of strerror(errno), but
110 usually it will do much better, and indicate the underlying cause in
111 more detail.
112 The errno global variable will be used to obtain the error value to be
114 decoded.
115 This function is intended to be used in a fashion similar to the fol‐
117 lowing example:
118 if (lseek(fd, offset, whence) == (off_t)-1)
119 {
120 char message[3000];
121 explain_message_lseek(message, sizeof(message), fd, offset, whence);
122 fprintf(stderr, '%s0, message);
123 exit(EXIT_FAILURE);
124 }
125 message The location in which to store the returned message. Because a
127 message return buffer has been supplied, this function is
128 thread safe.
129 message_size
131 The size in bytes of the location in which to store the
132 returned message.
133 fildes The original fildes, exactly as passed to the lseek(2) system
135 call.
136 offset The original offset, exactly as passed to the lseek(2) system
138 call.
139 whence The original whence, exactly as passed to the lseek(2) system
141 call.
142 explain_message_errno_lseek
144 void explain_message_errno_lseek(char *message, int message_size, int
145 errnum, int fildes, long long offset, int whence);
146 The explain_message_errno_lseek function may be used to obtain a human
148 readable explanation of what went wrong in an lseek(2) system call.
149 The least the message will contain is the value of strerror(errnum),
150 but usually it will do much better, and indicate the underlying cause
151 in more detail.
152 This function is intended to be used in a fashion similar to the fol‐
154 lowing example:
155 if (lseek(fd, offset, whence) == (off_t)-1)
156 {
157 char message[3000];
158 int errnum = errno;
159 explain_message_errno_lseek(message, sizeof(message), errnum, fd,
160 offset, whence);
161 fprintf(stderr, '%s0, message);
162 exit(EXIT_FAILURE);
163 }
164 message The location in which to store the returned message. Because a
166 message return buffer has been supplied, this function is
167 thread safe.
168 message_size
170 The size in bytes of the location in which to store the
171 returned message.
172 errnum The error value to be decoded, usually obtained from the errno
174 global variable just before this function is called. This is
175 necessary if you need to call any code between the system call
176 to be explained and this function, because many libc functions
177 will alter the value of errno.
178 fildes The original fildes, exactly as passed to the lseek(2) system
180 call.
181 offset The orginal offset, exactly as passed to the lseek(2) system
183 call.
184 whence The original whence, exactly as passed to the lseek(2) system
186 call.
187
189 libexplain version 1.4
190 Copyright (C) 2008 Peter Miller
191
193 Written by Peter Miller <pmiller@opensource.org.au>
194 explain_lseek(3)