1explain_chroot(3) Library Functions Manual explain_chroot(3)
2
6 explain_chroot - explain chroot(2) errors
7
9 #include <libexplain/chroot.h>
10 const char *explain_chroot(const char *pathname);
11 const char *explain_errno_chroot(int errnum, const char *pathname);
12 void explain_message_chroot(char *message, int message_size, const char
13 *pathname);
14 void explain_message_errno_chroot(char *message, int message_size, int
15 errnum, const char *pathname);
16
18 These functions may be used to obtain explanations for errors returned
19 by the chroot(2) system call.
20 explain_chroot
22 const char *explain_chroot(const char *pathname);
23 The explain_chroot function is used to obtain an explanation of an
25 error returned by the chroot(2) system call. The least the message will
26 contain is the value of strerror(errno), but usually it will do much
27 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 pathname
33 The original pathname, exactly as passed to the chroot(2) sys‐
34 tem call.
35 Returns:
37 The message explaining the error. This message buffer is shared
38 by all libexplain functions which do not supply a buffer in
39 their argument list. This will be overwritten by the next call
40 to any libexplain function which shares this buffer, including
41 other threads.
42 Note: This function is not thread safe, because it shares a return buf‐
44 fer across all threads, and many other functions in this library.
45 Example: This function is intended to be used in a fashion similar to
47 the following example:
48 if (chroot(pathname) < 0)
49 {
50 fprintf(stderr, "%s\n", explain_chroot(pathname));
51 exit(EXIT_FAILURE);
52 }
53 The above code example is available pre‐packaged as the
55 explain_chroot_or_die(3) function.
56 explain_errno_chroot
58 const char *explain_errno_chroot(int errnum, const char *pathname);
59 The explain_errno_chroot function is used to obtain an explanation of
61 an error returned by the chroot(2) system call. The least the message
62 will contain is the value of strerror(errno), but usually it will do
63 much better, and indicate the underlying cause in more detail.
64 errnum The error value to be decoded, usually obtained from the errno
66 global variable just before this function is called. This is
67 necessary if you need to call any code between the system call
68 to be explained and this function, because many libc functions
69 will alter the value of errno.
70 pathname
72 The original pathname, exactly as passed to the chroot(2) sys‐
73 tem call.
74 Returns:
76 The message explaining the error. This message buffer is shared
77 by all libexplain functions which do not supply a buffer in
78 their argument list. This will be overwritten by the next call
79 to any libexplain function which shares this buffer, including
80 other threads.
81 Note: This function is not thread safe, because it shares a return buf‐
83 fer across all threads, and many other functions in this library.
84 Example: This function is intended to be used in a fashion similar to
86 the following example:
87 if (chroot(pathname) < 0)
88 {
89 int err = errno;
90 fprintf(stderr, "%s\n", explain_errno_chroot(err, path‐
91 name));
92 exit(EXIT_FAILURE);
93 }
94 The above code example is available pre‐packaged as the
96 explain_chroot_or_die(3) function.
97 explain_message_chroot
99 void explain_message_chroot(char *message, int message_size, const char
100 *pathname);
101 The explain_message_chroot function is used to obtain an explanation of
103 an error returned by the chroot(2) system call. The least the message
104 will contain is the value of strerror(errno), but usually it will do
105 much better, and indicate the underlying cause in more detail.
106 The errno global variable will be used to obtain the error value to be
108 decoded.
109 message The location in which to store the returned message. If a suit‐
111 able message return buffer is supplied, this function is thread
112 safe.
113 message_size
115 The size in bytes of the location in which to store the
116 returned message.
117 pathname
119 The original pathname, exactly as passed to the chroot(2) sys‐
120 tem call.
121 Example: This function is intended to be used in a fashion similar to
123 the following example:
124 if (chroot(pathname) < 0)
125 {
126 char message[3000];
127 explain_message_chroot(message, sizeof(message), pathname);
128 fprintf(stderr, "%s\n", message);
129 exit(EXIT_FAILURE);
130 }
131 The above code example is available pre‐packaged as the
133 explain_chroot_or_die(3) function.
134 explain_message_errno_chroot
136 void explain_message_errno_chroot(char *message, int message_size, int
137 errnum, const char *pathname);
138 The explain_message_errno_chroot function is used to obtain an explana‐
140 tion of an error returned by the chroot(2) system call. The least the
141 message will contain is the value of strerror(errno), but usually it
142 will do much better, and indicate the underlying cause in more detail.
143 message The location in which to store the returned message. If a suit‐
145 able message return buffer is supplied, this function is thread
146 safe.
147 message_size
149 The size in bytes of the location in which to store the
150 returned message.
151 errnum The error value to be decoded, usually obtained from the errno
153 global variable just before this function is called. This is
154 necessary if you need to call any code between the system call
155 to be explained and this function, because many libc functions
156 will alter the value of errno.
157 pathname
159 The original pathname, exactly as passed to the chroot(2) sys‐
160 tem call.
161 Example: This function is intended to be used in a fashion similar to
163 the following example:
164 if (chroot(pathname) < 0)
165 {
166 int err = errno;
167 char message[3000];
168 explain_message_errno_chroot(message, sizeof(message), err,
169 pathname);
170 fprintf(stderr, "%s\n", message);
171 exit(EXIT_FAILURE);
172 }
173 The above code example is available pre‐packaged as the
175 explain_chroot_or_die(3) function.
176
178 chroot(2)
179 change root directory
180 explain_chroot_or_die(3)
182 change root directory and report errors
183
185 libexplain version 1.4
186 Copyright (C) 2009 Peter Miller
187 explain_chroot(3)