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

NAME

6       explain_putw - explain putw(3) errors
7

SYNOPSIS

9       #include <libexplain/putw.h>
10       const char *explain_putw(int value, FILE *fp);
11       const char *explain_errno_putw(int errnum, int value, FILE *fp);
12       void explain_message_putw(char *message, int message_size, int value,
13       FILE *fp);
14       void explain_message_errno_putw(char *message, int message_size, int
15       errnum, int value, FILE *fp);
16

DESCRIPTION

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

SEE ALSO

181       putw(3) output a word (int)
182
183       explain_putw_or_die(3)
184               output a word (int) and report errors
185
187       libexplain version 0.40
188       Copyright (C) 2010 Peter Miller
189
190
191
192                                                               explain_putw(3)
Impressum