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

NAME

6       explain_ftell - explain ftell(3) errors
7

SYNOPSIS

9       #include <libexplain/ftell.h>
10       const char *explain_ftell(FILE *fp);
11       const char *explain_errno_ftell(int errnum, FILE *fp);
12       void explain_message_ftell(char *message, int message_size, FILE *fp);
13       void explain_message_errno_ftell(char *message, int message_size, int
14       errnum, FILE *fp);
15

DESCRIPTION

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

SEE ALSO

171       ftell(3)
172               reposition a stream
173
174       explain_ftell_or_die(3)
175               reposition a stream and report errors
176
178       libexplain version 0.40
179       Copyright (C) 2010 Peter Miller
180
181
182
183                                                              explain_ftell(3)
Impressum