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

NAME

6       explain_chroot - explain chroot(2) errors
7

SYNOPSIS

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

DESCRIPTION

18       These  functions may be used to obtain explanations for errors returned
19       by the chroot(2) system call.
20
21   explain_chroot
22       const char *explain_chroot(const char *pathname);
23
24       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
29       The  errno global variable will be used to obtain the error value to be
30       decoded.
31
32       pathname
33               The original pathname, exactly as passed to the chroot(2)  sys‐
34               tem call.
35
36       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
43       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
46       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
54       The   above   code   example   is   available   pre‐packaged   as   the
55       explain_chroot_or_die(3) function.
56
57   explain_errno_chroot
58       const char *explain_errno_chroot(int errnum, const char *pathname);
59
60       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
65       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
71       pathname
72               The  original pathname, exactly as passed to the chroot(2) sys‐
73               tem call.
74
75       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
82       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
85       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
95       The   above   code   example   is   available   pre‐packaged   as   the
96       explain_chroot_or_die(3) function.
97
98   explain_message_chroot
99       void explain_message_chroot(char *message, int message_size, const char
100       *pathname);
101
102       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
107       The errno global variable will be used to obtain the error value to  be
108       decoded.
109
110       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
114       message_size
115               The  size  in  bytes  of  the  location  in  which to store the
116               returned message.
117
118       pathname
119               The original pathname, exactly as passed to the chroot(2)  sys‐
120               tem call.
121
122       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
132       The   above   code   example   is   available   pre‐packaged   as   the
133       explain_chroot_or_die(3) function.
134
135   explain_message_errno_chroot
136       void explain_message_errno_chroot(char *message, int message_size, int
137       errnum, const char *pathname);
138
139       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
144       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
148       message_size
149               The  size  in  bytes  of  the  location  in  which to store the
150               returned message.
151
152       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
158       pathname
159               The original pathname, exactly as passed to the chroot(2)  sys‐
160               tem call.
161
162       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
174       The   above   code   example   is   available   pre‐packaged   as   the
175       explain_chroot_or_die(3) function.
176

SEE ALSO

178       chroot(2)
179               change root directory
180
181       explain_chroot_or_die(3)
182               change root directory and report errors
183
185       libexplain version 0.40
186       Copyright (C) 2009 Peter Miller
187
188
189
190                                                             explain_chroot(3)
Impressum