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

NAME

6       explain_setlinebuf - explain setlinebuf(3) errors
7

SYNOPSIS

9       #include <libexplain/setlinebuf.h>
10       const char *explain_setlinebuf(FILE *fp);
11       const char *explain_errno_setlinebuf(int errnum, FILE *fp);
12       void explain_message_setlinebuf(char *message, int message_size, FILE
13       *fp);
14       void explain_message_errno_setlinebuf(char *message, int message_size,
15       int errnum, FILE *fp);
16

DESCRIPTION

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

SEE ALSO

183       setlinebuf(3)
184               stream buffering operations
185
186       explain_setlinebuf_or_die(3)
187               stream buffering operations and report errors
188
190       libexplain version 0.40
191       Copyright (C) 2010 Peter Miller
192
193
194
195                                                         explain_setlinebuf(3)
Impressum