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

NAME

6       explain_getw - explain getw(3) errors
7

SYNOPSIS

9       #include <libexplain/getw.h>
10       const char *explain_getw(FILE *fp);
11       const char *explain_errno_getw(int errnum, FILE *fp);
12       void explain_message_getw(char *message, int message_size, FILE *fp);
13       void explain_message_errno_getw(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 getw(3) system call.
19
20   explain_getw
21       const char *explain_getw(FILE *fp);
22
23       The  explain_getw function is used to obtain an explanation of an error
24       returned by the getw(3) system call. The least the message will contain
25       is  the  value  of strerror(errno), but usually it will do much better,
26       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 getw(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              int result = getw(fp);
46              if (result < 0)
47              {
48                  fprintf(stderr, "%s\n", explain_getw(fp));
49                  exit(EXIT_FAILURE);
50              }
51
52       The   above   code   example   is   available   pre‐packaged   as   the
53       explain_getw_or_die(3) function.
54
55   explain_errno_getw
56       const char *explain_errno_getw(int errnum, FILE *fp);
57
58       The explain_errno_getw function is used to obtain an explanation of  an
59       error  returned  by the getw(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 getw(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              int result = getw(fp);
84              if (result < 0)
85              {
86                  int err = errno;
87                  fprintf(stderr, "%s\n", explain_errno_getw(err, fp));
88                  exit(EXIT_FAILURE);
89              }
90
91       The   above   code   example   is   available   pre‐packaged   as   the
92       explain_getw_or_die(3) function.
93
94   explain_message_getw
95       void explain_message_getw(char *message, int message_size, FILE *fp);
96
97       The explain_message_getw function is used to obtain an  explanation  of
98       an  error  returned  by  the getw(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 getw(3) system call.
114
115       Example:  This  function is intended to be used in a fashion similar to
116       the following example:
117              int result = getw(fp);
118              if (result < 0)
119              {
120                  char message[3000];
121                  explain_message_getw(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_getw_or_die(3) function.
128
129   explain_message_errno_getw
130       void explain_message_errno_getw(char *message, int message_size, int
131       errnum, FILE *fp);
132
133       The explain_message_errno_getw function is used to obtain  an  explana‐
134       tion  of  an  error  returned by the getw(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 getw(3) system call.
153
154       Example: This function is intended to be used in a fashion  similar  to
155       the following example:
156              int result = getw(fp);
157              if (result < 0)
158              {
159                  int err = errno;
160                  char message[3000];
161                  explain_message_errno_getw(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_getw_or_die(3) function.
169

SEE ALSO

171       getw(3) input a word (int)
172
173       explain_getw_or_die(3)
174               input a word (int) and report errors
175
177       libexplain version 1.4
178       Copyright (C) 2010 Peter Miller
179
180
181
182                                                               explain_getw(3)
Impressum