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

NAME

6       explain_fsetpos - explain fsetpos(3) errors
7

SYNOPSIS

9       #include <libexplain/fsetpos.h>
10       const char *explain_fsetpos(FILE *fp, fpos_t *pos);
11       const char *explain_errno_fsetpos(int errnum, FILE *fp, fpos_t *pos);
12       void explain_message_fsetpos(char *message, int message_size, FILE *fp,
13       fpos_t *pos);
14       void explain_message_errno_fsetpos(char *message, int message_size, int
15       errnum, FILE *fp, fpos_t *pos);
16

DESCRIPTION

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

SEE ALSO

187       fsetpos(3)
188               reposition a stream
189
190       explain_fsetpos_or_die(3)
191               reposition a stream and report errors
192
194       libexplain version 1.4
195       Copyright (C) 2010 Peter Miller
196
197
198
199                                                            explain_fsetpos(3)
Impressum