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

NAME

6       explain_readlink - explain readlink(2) errors
7

SYNOPSIS

9       #include <libexplain/readlink.h>
10       const  char  *explain_readlink(const char *pathname, char *data, size_t
11       data_size);
12       const char *explain_errno_readlink(int errnum,  const  char  *pathname,
13       char *data, size_t data_size);
14       void  explain_message_readlink(char  *message,  int message_size, const
15       char *pathname, char *data, size_t data_size);
16       void explain_message_errno_readlink(char  *message,  int  message_size,
17       int errnum, const char *pathname, char *data, size_t data_size);
18

DESCRIPTION

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

SEE ALSO

201       readlink(2)
202               blah blah blah
203
204       explain_readlink_or_die(3)
205               blah blah blah  and report errors
206
208       libexplain version 0.40
209       Copyright (C) 2008 Peter Miller
210
211
212
213                                                           explain_readlink(3)
Impressum