1explain_execve(3) Library Functions Manual explain_execve(3)
2
6 explain_execve - explain execve(2) errors
7
9 #include <libexplain/execve.h>
10 const char *explain_execve(const char *pathname, const char *const
11 *argv, const char *const *envp);
12 const char *explain_errno_execve(int errnum, const char *pathname,
13 const char *const *argv, const char *const *envp);
14 void explain_message_execve(char *message, int message_size, const char
15 *pathname, const char *const *argv, const char *const *envp);
16 void explain_message_errno_execve(char *message, int message_size, int
17 errnum, const char *pathname, const char *const *argv, const char
18 *const *envp);
19
21 These functions may be used to obtain explanations for errors returned
22 by the execve(2) system call.
23 explain_execve
25 const char *explain_execve(const char *pathname, const char *const
26 *argv, const char *const *envp);
27 The explain_execve function is used to obtain an explanation of an
29 error returned by the execve(2) system call. The least the message
30 will contain is the value of strerror(errno), but usually it will do
31 much better, and indicate the underlying cause in more detail.
32 The errno global variable will be used to obtain the error value to be
34 decoded.
35 This function is intended to be used in a fashion similar to the fol‐
37 lowing example:
38 execve(pathname, argv, envp);
39 fprintf(stderr, "%s\n", explain_execve(pathname, argv, envp));
40 exit(EXIT_FAILURE);
41 pathname
43 The original pathname, exactly as passed to the execve(2) sys‐
44 tem call.
45 argv The original argv, exactly as passed to the execve(2) system
47 call.
48 envp The original envp, exactly as passed to the execve(2) system
50 call.
51 Returns:
53 The message explaining the error. This message buffer is
54 shared by all libexplain functions which do not supply a buffer
55 in their argument list. This will be overwritten by the next
56 call to any libexplain function which shares this buffer,
57 including other threads.
58 Note: This function is not thread safe, because it shares a return buf‐
60 fer across all threads, and many other functions in this library.
61 explain_errno_execve
63 const char *explain_errno_execve(int errnum, const char *pathname,
64 const char *const *argv, const char *const *envp);
65 The explain_errno_execve function is used to obtain an explanation of
67 an error returned by the execve(2) system call. The least the message
68 will contain is the value of strerror(errnum), but usually it will do
69 much better, and indicate the underlying cause in more detail.
70 This function is intended to be used in a fashion similar to the fol‐
72 lowing example:
73 execve(pathname, argv, envp);
74 int err = errno;
75 fprintf(stderr, "%s\n", explain_errno_execve(err, pathname, argv, envp));
76 exit(EXIT_FAILURE);
77 errnum The error value to be decoded, usually obtained from the errno
79 global variable just before this function is called. This is
80 necessary if you need to call any code between the system call
81 to be explained and this function, because many libc functions
82 will alter the value of errno.
83 pathname
85 The original pathname, exactly as passed to the execve(2) sys‐
86 tem call.
87 argv The original argv, exactly as passed to the execve(2) system
89 call.
90 envp The original envp, exactly as passed to the execve(2) system
92 call.
93 Returns:
95 The message explaining the error. This message buffer is
96 shared by all libexplain functions which do not supply a buffer
97 in their argument list. This will be overwritten by the next
98 call to any libexplain function which shares this buffer,
99 including other threads.
100 Note: This function is not thread safe, because it shares a return buf‐
102 fer across all threads, and many other functions in this library.
103 explain_message_execve
105 void explain_message_execve(char *message, int message_size, const char
106 *pathname, const char *const *argv, const char *const *envp);
107 The explain_message_execve function may be used to obtain an explana‐
109 tion of an error returned by the execve(2) system call. The least the
110 message will contain is the value of strerror(errno), but usually it
111 will do much better, and indicate the underlying cause in more detail.
112 The errno global variable will be used to obtain the error value to be
114 decoded.
115 This function is intended to be used in a fashion similar to the fol‐
117 lowing example:
118 execve(pathname, argv, envp);
119 char message[3000];
120 explain_message_execve(message, sizeof(message), pathname, argv, envp);
121 fprintf(stderr, "%s\n", message);
122 exit(EXIT_FAILURE);
123 message The location in which to store the returned message. If a
125 suitable message return buffer is supplied, this function is
126 thread safe.
127 message_size
129 The size in bytes of the location in which to store the
130 returned message.
131 pathname
133 The original pathname, exactly as passed to the execve(2) sys‐
134 tem call.
135 argv The original argv, exactly as passed to the execve(2) system
137 call.
138 envp The original envp, exactly as passed to the execve(2) system
140 call.
141 explain_message_errno_execve
143 void explain_message_errno_execve(char *message, int message_size, int
144 errnum, const char *pathname, const char *const *argv, const char
145 *const *envp);
146 The explain_message_errno_execve function may be used to obtain an
148 explanation of an error returned by the execve(2) system call. The
149 least the message will contain is the value of strerror(errnum), but
150 usually it will do much better, and indicate the underlying cause in
151 more detail.
152 This function is intended to be used in a fashion similar to the fol‐
154 lowing example:
155 execve(pathname, argv, envp);
156 int err = errno;
157 char message[3000];
158 explain_message_errno_execve(message, sizeof(message), err,
159 pathname, argv, envp);
160 fprintf(stderr, "%s\n", message);
161 exit(EXIT_FAILURE);
162 message The location in which to store the returned message. If a
164 suitable message return buffer is supplied, this function is
165 thread safe.
166 message_size
168 The size in bytes of the location in which to store the
169 returned message.
170 errnum The error value to be decoded, usually obtained from the errno
172 global variable just before this function is called. This is
173 necessary if you need to call any code between the system call
174 to be explained and this function, because many libc functions
175 will alter the value of errno.
176 pathname
178 The original pathname, exactly as passed to the execve(2) sys‐
179 tem call.
180 argv The original argv, exactly as passed to the execve(2) system
182 call.
183 envp The original envp, exactly as passed to the execve(2) system
185 call.
186
188 execve(2)
189 execute program
190 explain_execve_or_die(3)
192 execute program and report errors
193
195 libexplain version 1.4
196 Copyright (C) 2008 Peter Miller
197 explain_execve(3)