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

NAME

6       explain_stat - explain stat(2) errors
7

SYNOPSIS

9       #include <libexplain/stat.h>
10       const char *explain_stat(const char *pathname, const struct stat *buf);
11       void  explain_message_stat(char  *message, int message_size, const char
12       *pathname, const struct stat *buf);
13       const char *explain_errno_stat(int errnum, const char *pathname,  const
14       struct stat *buf);
15       void  explain_message_errno_stat(char  *message,  int message_size, int
16       errnum, const char *pathname, const struct stat *buf);
17

DESCRIPTION

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

AUTHOR

179       Written by Peter Miller <pmiller@opensource.org.au>
180
181
182
183                                                               explain_stat(3)
Impressum