1explain_ptrace(3) Library Functions Manual explain_ptrace(3)
2
6 explain_ptrace - explain ptrace(2) errors
7
9 #include <libexplain/ptrace.h>
10 const char *explain_ptrace(int request, pid_t pid, void *addr, void
11 *data);
12 const char *explain_errno_ptrace(int errnum, int request, pid_t pid,
13 void *addr, void *data);
14 void explain_message_ptrace(char *message, int message_size, int
15 request, pid_t pid, void *addr, void *data);
16 void explain_message_errno_ptrace(char *message, int message_size, int
17 errnum, int request, pid_t pid, void *addr, void *data);
18
20 These functions may be used to obtain explanations for errors returned
21 by the ptrace(2) system call.
22 explain_ptrace
24 const char *explain_ptrace(int request, pid_t pid, void *addr, void
25 *data);
26 The explain_ptrace function is used to obtain an explanation of an
28 error returned by the ptrace(2) system call. The least the message will
29 contain is the value of strerror(errno), but usually it will do much
30 better, and indicate the underlying cause in more detail.
31 The errno global variable will be used to obtain the error value to be
33 decoded.
34 request The original request, exactly as passed to the ptrace(2) system
36 call.
37 pid The original pid, exactly as passed to the ptrace(2) system
39 call.
40 addr The original addr, exactly as passed to the ptrace(2) system
42 call.
43 data The original data, exactly as passed to the ptrace(2) system
45 call.
46 Returns:
48 The message explaining the error. This message buffer is shared
49 by all libexplain functions which do not supply a buffer in
50 their argument list. This will be overwritten by the next call
51 to any libexplain function which shares this buffer, including
52 other threads.
53 Note: This function is not thread safe, because it shares a return buf‐
55 fer across all threads, and many other functions in this library.
56 Example: This function is intended to be used in a fashion similar to
58 the following example:
59 long result = ptrace(request, pid, addr, data);
60 if (result < 0)
61 {
62 fprintf(stderr, "%s\n", explain_ptrace(request, pid, addr,
63 data));
64 exit(EXIT_FAILURE);
65 }
66 The above code example is available pre-packaged as the
68 explain_ptrace_or_die(3) function.
69 explain_errno_ptrace
71 const char *explain_errno_ptrace(int errnum, int request, pid_t pid,
72 void *addr, void *data);
73 The explain_errno_ptrace function is used to obtain an explanation of
75 an error returned by the ptrace(2) system call. The least the message
76 will contain is the value of strerror(errno), but usually it will do
77 much better, and indicate the underlying cause in more detail.
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 request The original request, exactly as passed to the ptrace(2) system
86 call.
87 pid The original pid, exactly as passed to the ptrace(2) system
89 call.
90 addr The original addr, exactly as passed to the ptrace(2) system
92 call.
93 data The original data, exactly as passed to the ptrace(2) system
95 call.
96 Returns:
98 The message explaining the error. This message buffer is shared
99 by all libexplain functions which do not supply a buffer in
100 their argument list. This will be overwritten by the next call
101 to any libexplain function which shares this buffer, including
102 other threads.
103 Note: This function is not thread safe, because it shares a return buf‐
105 fer across all threads, and many other functions in this library.
106 Example: This function is intended to be used in a fashion similar to
108 the following example:
109 long result = ptrace(request, pid, addr, data);
110 if (result < 0)
111 {
112 int err = errno;
113 fprintf(stderr, "%s\n", explain_errno_ptrace(err, request,
114 pid, addr, data));
115 exit(EXIT_FAILURE);
116 }
117 The above code example is available pre-packaged as the
119 explain_ptrace_or_die(3) function.
120 explain_message_ptrace
122 void explain_message_ptrace(char *message, int message_size, int
123 request, pid_t pid, void *addr, void *data);
124 The explain_message_ptrace function is used to obtain an explanation of
126 an error returned by the ptrace(2) system call. The least the message
127 will contain is the value of strerror(errno), but usually it will do
128 much better, and indicate the underlying cause in more detail.
129 The errno global variable will be used to obtain the error value to be
131 decoded.
132 message The location in which to store the returned message. If a suit‐
134 able message return buffer is supplied, this function is thread
135 safe.
136 message_size
138 The size in bytes of the location in which to store the
139 returned message.
140 request The original request, exactly as passed to the ptrace(2) system
142 call.
143 pid The original pid, exactly as passed to the ptrace(2) system
145 call.
146 addr The original addr, exactly as passed to the ptrace(2) system
148 call.
149 data The original data, exactly as passed to the ptrace(2) system
151 call.
152 Example: This function is intended to be used in a fashion similar to
154 the following example:
155 long result = ptrace(request, pid, addr, data);
156 if (result < 0)
157 {
158 char message[3000];
159 explain_message_ptrace(message, sizeof(message), request,
160 pid, addr, data);
161 fprintf(stderr, "%s\n", message);
162 exit(EXIT_FAILURE);
163 }
164 The above code example is available pre-packaged as the
166 explain_ptrace_or_die(3) function.
167 explain_message_errno_ptrace
169 void explain_message_errno_ptrace(char *message, int message_size, int
170 errnum, int request, pid_t pid, void *addr, void *data);
171 The explain_message_errno_ptrace function is used to obtain an explana‐
173 tion of an error returned by the ptrace(2) system call. The least the
174 message will contain is the value of strerror(errno), but usually it
175 will do much better, and indicate the underlying cause in more detail.
176 message The location in which to store the returned message. If a suit‐
178 able message return buffer is supplied, this function is thread
179 safe.
180 message_size
182 The size in bytes of the location in which to store the
183 returned message.
184 errnum The error value to be decoded, usually obtained from the errno
186 global variable just before this function is called. This is
187 necessary if you need to call any code between the system call
188 to be explained and this function, because many libc functions
189 will alter the value of errno.
190 request The original request, exactly as passed to the ptrace(2) system
192 call.
193 pid The original pid, exactly as passed to the ptrace(2) system
195 call.
196 addr The original addr, exactly as passed to the ptrace(2) system
198 call.
199 data The original data, exactly as passed to the ptrace(2) system
201 call.
202 Example: This function is intended to be used in a fashion similar to
204 the following example:
205 long result = ptrace(request, pid, addr, data);
206 if (result < 0)
207 {
208 int err = errno;
209 char message[3000];
210 explain_message_errno_ptrace(message, sizeof(message), err,
211 request, pid, addr, data);
212 fprintf(stderr, "%s\n", message);
213 exit(EXIT_FAILURE);
214 }
215 The above code example is available pre-packaged as the
217 explain_ptrace_or_die(3) function.
218
220 ptrace(2)
221 process trace
222 explain_ptrace_or_die(3)
224 process trace and report errors
225
227 libexplain version 1.4
228 Copyright (C) 2010 Peter Miller
229 explain_ptrace(3)