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

NAME

6       explain_putc - explain putc(3) errors
7

SYNOPSIS

9       #include <libexplain/putc.h>
10       const char *explain_putc(int c, FILE *fp);
11       const char *explain_errno_putc(int errnum, int c, FILE *fp);
12       void  explain_message_putc(char *message, int message_size, int c, FILE
13       *fp);
14       void explain_message_errno_putc(char *message,  int  message_size,  int
15       errnum, int c, FILE *fp);
16

DESCRIPTION

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

SEE ALSO

164       putc(3) output of characters
165
166       explain_putc_or_die(3)
167               output of characters and report errors
168
170       libexplain version 0.40
171       Copyright (C) 2008 Peter Miller
172
173
174
175                                                               explain_putc(3)
Impressum