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

NAME

6       explain_readdir - explain readdir(2) errors
7

SYNOPSIS

9       #include <libexplain/readdir.h>
10       const char *explain_readdir(DIR *dir);
11       const char *explain_errno_readdir(int errnum, DIR *dir);
12       void   explain_message_readdir(char  *message,  int  message_size,  DIR
13       *dir);
14       void explain_message_errno_readdir(char *message, int message_size, int
15       errnum, DIR *dir);
16

DESCRIPTION

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

SEE ALSO

169       readdir(2)
170               read directory entry
171
172       explain_readdir_or_die(3)
173               read directory entry and report errors
174
176       libexplain version 0.40
177       Copyright (C) 2008 Peter Miller
178
179
180
181                                                            explain_readdir(3)
Impressum