1explain_getcwd(3) Library Functions Manual explain_getcwd(3)
2
6 explain_getcwd - explain getcwd(2) errors
7
9 #include <libexplain/getcwd.h>
10 const char *explain_getcwd(char *buf, size_t size);
11 const char *explain_errno_getcwd(int errnum, char *buf, size_t size);
12 void explain_message_getcwd(char *message, int message_size, char *buf,
13 size_t size);
14 void explain_message_errno_getcwd(char *message, int message_size, int
15 errnum, char *buf, size_t size);
16
18 These functions may be used to obtain explanations for errors returned
19 by the getcwd(2) system call.
20 explain_getcwd
22 const char *explain_getcwd(char *buf, size_t size);
23 The explain_getcwd function is used to obtain an explanation of an
25 error returned by the getcwd(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 The errno global variable will be used to obtain the error value to be
30 decoded.
31 This function is intended to be used in a fashion similar to the fol‐
33 lowing example:
34 if (getcwd(buf, size) < 0)
35 {
36 fprintf(stderr, "%s\n", explain_getcwd(buf, size));
37 exit(EXIT_FAILURE);
38 }
39 The above code example is available pre‐packaged as the
41 explain_getcwd_or_die(3) function.
42 buf The original buf, exactly as passed to the getcwd(2) system
44 call.
45 size The original size, exactly as passed to the getcwd(2) system
47 call.
48 Returns:
50 The message explaining the error. This message buffer is
51 shared by all libexplain functions which do not supply a buffer
52 in their argument list. This will be overwritten by the next
53 call to any libexplain function which shares this buffer,
54 including other threads.
55 Note: This function is not thread safe, because it shares a return buf‐
57 fer across all threads, and many other functions in this library.
58 explain_errno_getcwd
60 const char *explain_errno_getcwd(int errnum, char *buf, size_t size);
61 The explain_errno_getcwd function is used to obtain an explanation of
63 an error returned by the getcwd(2) system call. The least the message
64 will contain is the value of strerror(errnum), but usually it will do
65 much better, and indicate the underlying cause in more detail.
66 This function is intended to be used in a fashion similar to the fol‐
68 lowing example:
69 if (getcwd(buf, size) < 0)
70 {
71 int err = errno;
72 fprintf(stderr, "%s\n", explain_errno_getcwd(err, buf, size));
73 exit(EXIT_FAILURE);
74 }
75 The above code example is available pre‐packaged as the
77 explain_getcwd_or_die(3) function.
78 errnum The error value to be decoded, usually obtained from the errno
80 global variable just before this function is called. This is
81 necessary if you need to call any code between the system call
82 to be explained and this function, because many libc functions
83 will alter the value of errno.
84 buf The original buf, exactly as passed to the getcwd(2) system
86 call.
87 size The original size, exactly as passed to the getcwd(2) system
89 call.
90 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 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 explain_message_getcwd
102 void explain_message_getcwd(char *message, int message_size, char *buf,
103 size_t size);
104 The explain_message_getcwd function may be used to obtain an explana‐
106 tion of an error returned by the getcwd(2) system call. The least the
107 message will contain is the value of strerror(errno), but usually it
108 will do much better, and indicate the underlying cause in more detail.
109 The errno global variable will be used to obtain the error value to be
111 decoded.
112 This function is intended to be used in a fashion similar to the fol‐
114 lowing example:
115 if (getcwd(buf, size) < 0)
116 {
117 char message[3000];
118 explain_message_getcwd(message, sizeof(message), buf, size);
119 fprintf(stderr, "%s\n", message);
120 exit(EXIT_FAILURE);
121 }
122 The above code example is available pre‐packaged as the
124 explain_getcwd_or_die(3) function.
125 message The location in which to store the returned message. If a
127 suitable message return buffer is supplied, this function is
128 thread safe.
129 message_size
131 The size in bytes of the location in which to store the
132 returned message.
133 buf The original buf, exactly as passed to the getcwd(2) system
135 call.
136 size The original size, exactly as passed to the getcwd(2) system
138 call.
139 explain_message_errno_getcwd
141 void explain_message_errno_getcwd(char *message, int message_size, int
142 errnum, char *buf, size_t size);
143 The explain_message_errno_getcwd function may be used to obtain an
145 explanation of an error returned by the getcwd(2) system call. The
146 least the message will contain is the value of strerror(errnum), but
147 usually it will do much better, and indicate the underlying cause in
148 more detail.
149 This function is intended to be used in a fashion similar to the fol‐
151 lowing example:
152 if (getcwd(buf, size) < 0)
153 {
154 int err = errno;
155 char message[3000];
156 explain_message_errno_getcwd(message, sizeof(message), err, buf, size);
157 fprintf(stderr, "%s\n", message);
158 exit(EXIT_FAILURE);
159 }
160 The above code example is available pre‐packaged as the
162 explain_getcwd_or_die(3) function.
163 message The location in which to store the returned message. If a
165 suitable message return buffer is supplied, this function is
166 thread safe.
167 message_size
169 The size in bytes of the location in which to store the
170 returned message.
171 errnum The error value to be decoded, usually obtained from the errno
173 global variable just before this function is called. This is
174 necessary if you need to call any code between the system call
175 to be explained and this function, because many libc functions
176 will alter the value of errno.
177 buf The original buf, exactly as passed to the getcwd(2) system
179 call.
180 size The original size, exactly as passed to the getcwd(2) system
182 call.
183
185 getcwd(2)
186 Get current working directory
187 explain_getcwd_or_die(3)
189 Get current working directory and report errors
190
192 libexplain version 0.40
193 Copyright (C) 2008 Peter Miller
194 explain_getcwd(3)