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

NAME

6       explain_lstat - explain lstat(3) errors
7

SYNOPSIS

9       #include <libexplain/lstat.h>
10       const  char  *explain_lstat(const  char  *pathname,  const  struct stat
11       *buf);
12       void explain_message_lstat(char *message, int message_size, const  char
13       *pathname, const struct stat *buf);
14       const char *explain_errno_lstat(int errnum, const char *pathname, const
15       struct stat *buf);
16       void explain_message_errno_lstat(char *message, int  message_size,  int
17       errnum, const char *pathname, const struct stat *buf);
18

DESCRIPTION

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

AUTHOR

185       Written by Peter Miller <pmiller@opensource.org.au>
186
187
188
189                                                              explain_lstat(3)
Impressum