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

NAME

6       explain_fdopendir - explain fdopendir(3) errors
7

SYNOPSIS

9       #include <libexplain/fdopendir.h>
10       const char *explain_fdopendir(int fildes);
11       const char *explain_errno_fdopendir(int errnum, int fildes);
12       void explain_message_fdopendir(char *message, int message_size, int
13       fildes);
14       void explain_message_errno_fdopendir(char *message, int message_size,
15       int errnum, int fildes);
16

DESCRIPTION

18       These  functions may be used to obtain explanations for errors returned
19       by the fdopendir(3) system call.
20
21   explain_fdopendir
22       const char *explain_fdopendir(int fildes);
23
24       The explain_fdopendir function is used to obtain an explanation  of  an
25       error  returned  by the fdopendir(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       fildes  The original fildes, exactly as passed to the fdopendir(3) sys‐
33               tem 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              DIR *result = fdopendir(fildes);
48              if (!result)
49              {
50                  fprintf(stderr, "%s\n", explain_fdopendir(fildes));
51                  exit(EXIT_FAILURE);
52              }
53
54       The   above   code   example   is   available   pre‐packaged   as   the
55       explain_fdopendir_or_die(3) function.
56
57   explain_errno_fdopendir
58       const char *explain_errno_fdopendir(int errnum, int fildes);
59
60       The explain_errno_fdopendir function is used to obtain  an  explanation
61       of  an  error  returned by the fdopendir(3) system call.  The least the
62       message will contain is the value of strerror(errno),  but  usually  it
63       will do much 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       fildes  The original fildes, exactly as passed to the fdopendir(3) sys‐
72               tem call.
73
74       Returns:
75               The message explaining the error. This message buffer is shared
76               by  all  libexplain  functions  which do not supply a buffer in
77               their argument list.  This will be overwritten by the next call
78               to  any libexplain function which shares this buffer, including
79               other threads.
80
81       Note: This function is not thread safe, because it shares a return buf‐
82       fer across all threads, and many other functions in this library.
83
84       Example:  This  function is intended to be used in a fashion similar to
85       the following example:
86              DIR *result = fdopendir(fildes);
87              if (!result)
88              {
89                  int err = errno;
90                  fprintf(stderr, "%s\n", explain_errno_fdopendir(err,
91                  fildes));
92                  exit(EXIT_FAILURE);
93              }
94
95       The   above   code   example   is   available   pre‐packaged   as   the
96       explain_fdopendir_or_die(3) function.
97
98   explain_message_fdopendir
99       void explain_message_fdopendir(char *message, int message_size, int
100       fildes);
101
102       The explain_message_fdopendir function is used to obtain an explanation
103       of an error returned by the fdopendir(3) system call.   The  least  the
104       message  will  contain  is the value of strerror(errno), but usually it
105       will do much better, and indicate the underlying cause in more detail.
106
107       The errno global variable will be used to obtain the error value to  be
108       decoded.
109
110       message The location in which to store the returned message. If a suit‐
111               able message return buffer is supplied, this function is thread
112               safe.
113
114       message_size
115               The  size  in  bytes  of  the  location  in  which to store the
116               returned message.
117
118       fildes  The original fildes, exactly as passed to the fdopendir(3) sys‐
119               tem call.
120
121       Example:  This  function is intended to be used in a fashion similar to
122       the following example:
123              DIR *result = fdopendir(fildes);
124              if (!result)
125              {
126                  char message[3000];
127                  explain_message_fdopendir(message, sizeof(message), fildes);
128                  fprintf(stderr, "%s\n", message);
129                  exit(EXIT_FAILURE);
130              }
131
132       The   above   code   example   is   available   pre‐packaged   as   the
133       explain_fdopendir_or_die(3) function.
134
135   explain_message_errno_fdopendir
136       void explain_message_errno_fdopendir(char *message, int message_size,
137       int errnum, int fildes);
138
139       The explain_message_errno_fdopendir  function  is  used  to  obtain  an
140       explanation  of an error returned by the fdopendir(3) system call.  The
141       least the message will contain is the  value  of  strerror(errno),  but
142       usually  it  will  do much better, and indicate the underlying cause in
143       more detail.
144
145       message The location in which to store the returned message. If a suit‐
146               able message return buffer is supplied, this function is thread
147               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       fildes  The original fildes, exactly as passed to the fdopendir(3) sys‐
160               tem call.
161
162       Example: This function is intended to be used in a fashion  similar  to
163       the following example:
164              DIR *result = fdopendir(fildes);
165              if (!result)
166              {
167                  int err = errno;
168                  char message[3000];
169                  explain_message_errno_fdopendir(message, sizeof(message),
170                  err, fildes);
171                  fprintf(stderr, "%s\n", message);
172                  exit(EXIT_FAILURE);
173              }
174
175       The   above   code   example   is   available   pre‐packaged   as   the
176       explain_fdopendir_or_die(3) function.
177

SEE ALSO

179       fdopendir(3)
180               open a directory
181
182       explain_fdopendir_or_die(3)
183               open a directory and report errors
184
186       libexplain version 1.4
187       Copyright (C) 2009 Peter Miller
188
189
190
191                                                          explain_fdopendir(3)
Impressum