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

NAME

6       explain_fseek - explain fseek(3) errors
7

SYNOPSIS

9       #include <libexplain/fseek.h>
10       const char *explain_fseek(FILE *fp, long offset, int whence);
11       const char *explain_errno_fseek(int errnum, FILE *fp, long offset, int
12       whence);
13       void explain_message_fseek(char *message, int message_size, FILE *fp,
14       long offset, int whence);
15       void explain_message_errno_fseek(char *message, int message_size, int
16       errnum, FILE *fp, long offset, int whence);
17

DESCRIPTION

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

SEE ALSO

197       fseek(3)
198               reposition a stream
199
200       explain_fseek_or_die(3)
201               reposition a stream and report errors
202
204       libexplain version 0.40
205       Copyright (C) 2010 Peter Miller
206
207
208
209                                                              explain_fseek(3)
Impressum