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

NAME

6       explain_fstat - explain fstat(2) errors
7

SYNOPSIS

9       #include <libexplain/fstat.h>
10       const char *explain_fstat(int fildes, struct stat *buf);
11       const  char  *explain_errno_fstat(int  errnum,  int fildes, struct stat
12       *buf);
13       void explain_message_fstat(char *message, int message_size, int fildes,
14       struct stat *buf);
15       void  explain_message_errno_fstat(char  *message, int message_size, int
16       errnum, int fildes, struct stat *buf);
17

DESCRIPTION

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

SEE ALSO

175       fstat(2)
176               get file status
177
178       explain_fstat_or_die(3)
179               get file status and report errors
180
182       libexplain version 0.40
183       Copyright (C) 2008 Peter Miller
184
185
186
187                                                              explain_fstat(3)
Impressum