explain_fputs(3)

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

NAME

6       explain_fputs - explain fputs(3) errors
7

SYNOPSIS

9       #include <libexplain/fputs.h>
10       const char *explain_fputs(const char *s, FILE *fp);
11       const char *explain_errno_fputs(int errnum, const char *s, FILE *fp);
12       void explain_message_fputs(char *message, int message_size, const char
13       *s, FILE *fp);
14       void explain_message_errno_fputs(char *message, int message_size, int
15       errnum, const char *s, FILE *fp);
16

DESCRIPTION

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

COPYRIGHT

184       libexplain version 0.40
185       Copyright (C) 2009 Peter Miller
186
187
188
189                                                              explain_fputs(3)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

COPYRIGHT