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

NAME

6       explain_execve - explain execve(2) errors
7

SYNOPSIS

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

DESCRIPTION

21       These functions may be used to obtain explanations for errors  returned
22       by the execve(2) system call.
23
24   explain_execve
25       const  char  *explain_execve(const  char  *pathname,  const char *const
26       *argv, const char *const *envp);
27
28       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
33       The  errno global variable will be used to obtain the error value to be
34       decoded.
35
36       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
42       pathname
43               The  original pathname, exactly as passed to the execve(2) sys‐
44               tem call.
45
46       argv    The original argv, exactly as passed to  the  execve(2)  system
47               call.
48
49       envp    The  original  envp,  exactly as passed to the execve(2) system
50               call.
51
52       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
59       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
62   explain_errno_execve
63       const  char  *explain_errno_execve(int  errnum,  const  char *pathname,
64       const char *const *argv, const char *const *envp);
65
66       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
71       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
78       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
84       pathname
85               The original pathname, exactly as passed to the execve(2)  sys‐
86               tem call.
87
88       argv    The  original  argv,  exactly as passed to the execve(2) system
89               call.
90
91       envp    The original envp, exactly as passed to  the  execve(2)  system
92               call.
93
94       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
101       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
104   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
108       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
113       The errno global variable will be used to obtain the error value to  be
114       decoded.
115
116       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
124       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
128       message_size
129               The size in bytes  of  the  location  in  which  to  store  the
130               returned message.
131
132       pathname
133               The  original pathname, exactly as passed to the execve(2) sys‐
134               tem call.
135
136       argv    The original argv, exactly as passed to  the  execve(2)  system
137               call.
138
139       envp    The  original  envp,  exactly as passed to the execve(2) system
140               call.
141
142   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
147       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
153       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
163       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
167       message_size
168               The  size  in  bytes  of  the  location  in  which to store the
169               returned message.
170
171       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
177       pathname
178               The original pathname, exactly as passed to the execve(2)  sys‐
179               tem call.
180
181       argv    The  original  argv,  exactly as passed to the execve(2) system
182               call.
183
184       envp    The original envp, exactly as passed to  the  execve(2)  system
185               call.
186

SEE ALSO

188       execve(2)
189               execute program
190
191       explain_execve_or_die(3)
192               execute program and report errors
193
195       libexplain version 0.40
196       Copyright (C) 2008 Peter Miller
197
198
199
200                                                             explain_execve(3)
Impressum