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

NAME

6       explain_fopen - explain fopen(3) errors
7

SYNOPSIS

9       #include <libexplain/fopen.h>
10       const char *explain_fopen(const char *path, const char *mode);
11       const  char  *explain_errno_fopen(int  errnum,  const char *path, const
12       char *mode);
13       void explain_message_fopen(char *message, int message_size, const  char
14       *path, const char *mode);
15       void  explain_message_errno_fopen(char  *message, int message_size, int
16       errnum, const char *path, const char *mode);
17

DESCRIPTION

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

AUTHOR

183       Written by Peter Miller <pmiller@opensource.org.au>
184
185
186
187                                                              explain_fopen(3)
Impressum