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

NAME

6       explain_pclose - explain pclose(3) errors
7

SYNOPSIS

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

SEE ALSO

171       pclose(3)
172               process I/O
173
174       explain_pclose_or_die(3)
175               process I/O and report errors
176
178       libexplain version 0.40
179       Copyright (C) 2009 Peter Miller
180
181
182
183                                                             explain_pclose(3)
Impressum