2 * This file is part of ltrace.
3 * Copyright (C) 2012 Petr Machata, Red Hat Inc.
5 * This program is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU General Public License as
7 * published by the Free Software Foundation; either version 2 of the
8 * License, or (at your option) any later version.
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
30 ps_invalid, /* Failure. */
31 ps_stop, /* Job-control stop. */
35 ps_other, /* Necessary other states can be added as needed. */
39 * This file contains documentation of back end interface. Some of
40 * these may be implemented on an OS level (i.e. they are the same
41 * e.g. on all Linux architectures), some may differ per architecture
42 * on the same OS (e.g. a way to insert a breakpoint into the process
43 * image is a likely candidate).
46 /* Convert a PID to a path to the corresponding binary. */
47 char *pid2name(pid_t pid);
49 /* Given a PID, find a leader of thread group. */
50 pid_t process_leader(pid_t pid);
52 /* Given a PID of leader thread, fill in PIDs of all the tasks. The
53 * function will initialize the pointer *RET_TASKS to a
54 * newly-allocated array, and will store number of elements in that
55 * array to *RET_N. You have to free that buffer when you don't need
57 int process_tasks(pid_t pid, pid_t **ret_tasks, size_t *ret_n);
59 /* Answer whether the process PID is stopped. Returns 0 when not
60 * stopped, 1 when stopped, or -1 when there was an error. */
61 int process_stopped(pid_t pid);
63 /* Answer a status of the task PID. See enum process_status. */
64 enum process_status process_status(pid_t pid);
66 /* Wait for PID to be ready for tracing. */
67 int wait_for_proc(pid_t pid);
69 /* Send a signal SIG to the task PID. */
70 int task_kill(pid_t pid, int sig);
72 /* Called after PID is attached, but before it is continued. */
73 void trace_set_options(struct Process *proc);
75 /* Called after ltrace forks. Should attach the newly created child,
76 * in whose context this function is called. */
79 /* Called when ltrace needs to attach to PID, such as when it attaches
80 * to a running process, whose PID is given on the command line. */
81 int trace_pid(pid_t pid);
83 /* Stop tracing PID. */
84 void untrace_pid(pid_t pid);
86 /* The back end may need to store arbitrary data to a process. This
87 * is a place where it can initialize PROC->arch_dep. XXX this should
88 * be dropped in favor of arhc_process_init on pmachata/libs. */
89 void get_arch_dep(struct Process *proc);
91 /* Return current instruction pointer of PROC.
93 * XXX note that the IP must fit into an arch pointer. This prevents
94 * us to use 32-bit ltrace to trace 64-bit process, even on arches
95 * that would otherwise support this. Above we have a definition of
96 * arch_addr_t. This should be converted to an integral type and
97 * used for target addresses throughout. */
98 void *get_instruction_pointer(struct Process *proc);
100 /* Set instruction pointer of PROC to ADDR. XXX see above. */
101 void set_instruction_pointer(struct Process *proc, void *addr);
103 /* Return current stack pointer of PROC. XXX see above. */
104 void *get_stack_pointer(struct Process *proc);
106 /* Find and return caller address, i.e. the address where the current
107 * function returns. */
108 void *get_return_addr(struct Process *proc, void *stack_pointer);
110 /* Adjust PROC so that when the current function returns, it returns
112 void set_return_addr(struct Process *proc, void *addr);
114 /* Enable breakpoint SBP in process PROC. */
115 void enable_breakpoint(struct Process *proc, struct breakpoint *sbp);
117 /* Disable breakpoint SBP in process PROC. */
118 void disable_breakpoint(struct Process *proc, struct breakpoint *sbp);
120 /* Determine whether the event that we have just seen (and that is
121 * recorded in STATUS) was a syscall. If it was, return 1. If it was
122 * a return from syscall, return 2. In both cases, set *SYSNUM to the
123 * number of said syscall. If it wasn't a syscall, return 0. If
124 * there was an error, return -1. */
125 int syscall_p(struct Process *proc, int status, int *sysnum);
127 /* Continue execution of the process with given PID. */
128 void continue_process(pid_t pid);
130 /* Called after we received a signal SIGNUM. Should do whatever
131 * book-keeping is necessary and continue the process if
133 void continue_after_signal(pid_t pid, int signum);
135 /* Called after we received a system call SYSNUM. RET_P is 0 if this
136 * is system call, otherwise it's return from a system call. The
137 * callback should do whatever book-keeping is necessary and continue
138 * the process if necessary. */
139 void continue_after_syscall(struct Process *proc, int sysnum, int ret_p);
141 /* Called after we hit a breakpoint SBP. Should do whatever
142 * book-keeping is necessary and then continue the process. */
143 void continue_after_breakpoint(struct Process *proc, struct breakpoint *sbp);
145 /* Called after we received a vfork. Should do whatever book-keeping
146 * is necessary and continue the process if necessary. N.B. right
147 * now, with Linux/GNU the only back end, this is not necessary. I
148 * imagine other systems may be different. */
149 void continue_after_vfork(struct Process *proc);
151 /* Called when trace_me or primary trace_pid fail. This may plug in
152 * any platform-specific knowledge of why it could be so. */
153 void trace_fail_warning(pid_t pid);
155 /* A pair of functions called to initiate a detachment request when
156 * ltrace is about to exit. Their job is to undo any effects that
157 * tracing had and eventually detach process, perhaps by way of
158 * installing a process handler.
160 * OS_LTRACE_EXITING_SIGHANDLER is called from a signal handler
161 * context right after the signal was captured. It returns 1 if the
162 * request was handled or 0 if it wasn't.
164 * If the call to OS_LTRACE_EXITING_SIGHANDLER didn't handle the
165 * request, OS_LTRACE_EXITING is called when the next event is
166 * generated. Therefore it's called in "safe" context, without
167 * re-entrancy concerns, but it's only called after an even is
169 int os_ltrace_exiting_sighandler(void);
170 void os_ltrace_exiting(void);
172 /* Should copy COUNT bytes from address ADDR of process PROC to local
174 size_t umovebytes (struct Process *proc, void *addr, void *buf, size_t count);
176 /* Find out an address of symbol SYM in process PROC, and return.
177 * Returning NULL delays breakpoint insertion and enables heaps of
178 * arch-specific black magic that we should clean up some day.
180 * XXX the same points as for get_instruction_pointer apply. */
181 void *sym2addr(struct Process *proc, struct library_symbol *sym);
183 /* Obtain address of PLT entry corresponding to relocation RELA in
184 * file LTE. This is NDX-th PLT entry in the file.
186 * XXX should this return arch_addr_t? */
187 GElf_Addr arch_plt_sym_val(struct ltelf *lte, size_t ndx, GElf_Rela *rela);
189 /* Called at some point after we have attached to PROC. This callback
190 * should insert an introspection breakpoint for handling dynamic
191 * linker library loads. */
192 int linkmap_init(struct Process *proc, arch_addr_t dyn_addr);
194 /* This should produce and return the next event of one of the traced
195 * processes. The returned pointer will not be freed by the core and
196 * should be either statically allocated, or the management should be
197 * done some other way. */
198 struct Event *next_event(void);
200 /* Called when process PROC was removed. */
201 void process_removed(struct Process *proc);
203 /* This should extract entry point address and interpreter (dynamic
204 * linker) bias if possible. Returns 0 if there were no errors, -1
205 * otherwise. Sets *ENTRYP and *INTERP_BIASP to non-zero values if
206 * the corresponding value is known, or zero otherwise; this is not
207 * done for pointers that are NULL. */
208 int process_get_entry(struct Process *proc,
210 arch_addr_t *interp_biasp);
213 /* Optional callbacks
215 * Some callbacks are only available if backend (arch.h) has a certain
216 * define. If such a define is not present, default implementation
217 * (most often doing nothing at all) us used instead. This is used
218 * for gradual extensions of ltrace, so that backends that are not
219 * fully up to date, or that don't need certain functionality, keep
220 * working, while other backends take advantage of the optional
223 /* The following callbacks have to be implemented in backend if arch.h
224 * defines ARCH_HAVE_LTELF_DATA. Those are used to init and destroy
225 * LTE->arch. arch_elf_init returns 0 on success or a negative value
227 int arch_elf_init(struct ltelf *lte, struct library *lib);
228 void arch_elf_destroy(struct ltelf *lte);
230 /* The following callbacks have to be implemented in backend if arch.h
231 * defines ARCH_HAVE_BREAKPOINT_DATA. Those are used to init,
232 * destroy, and clone SBP->arch. arch_breakpoint_init and
233 * arch_breakpoint_clone return 0 on success or a negative value on
235 int arch_breakpoint_init(struct Process *proc, struct breakpoint *sbp);
236 void arch_breakpoint_destroy(struct breakpoint *sbp);
237 int arch_breakpoint_clone(struct breakpoint *retp, struct breakpoint *sbp);
239 /* The following callbacks have to be implemented in backend if arch.h
240 * defines ARCH_HAVE_LIBRARY_DATA. Those are used to init, destroy
241 * and clone LIB->arch. */
242 void arch_library_init(struct library *lib);
243 void arch_library_destroy(struct library *lib);
244 void arch_library_clone(struct library *retp, struct library *lib);
246 /* The following callbacks have to be implemented in backend if arch.h
247 * defines ARCH_HAVE_LIBRARY_SYMBOL_DATA. Those are used to init,
248 * destroy and clone LIBSYM->arch. arch_library_symbol_init and
249 * arch_library_symbol_clone return 0 on success or a negative value
251 int arch_library_symbol_init(struct library_symbol *libsym);
252 void arch_library_symbol_destroy(struct library_symbol *libsym);
253 int arch_library_symbol_clone(struct library_symbol *retp,
254 struct library_symbol *libsym);
256 /* The following callbacks have to be implemented in backend if arch.h
257 * defines ARCH_HAVE_PROCESS_DATA. Those are used to init, destroy
258 * and clone PROC->arch. arch_process_exec is called to update
259 * PROC->arch in case that PROC underwent an exec. See notes at
260 * process_init, process_destroy, process_clone and process_exec in
262 int arch_process_init(struct Process *proc);
263 void arch_process_destroy(struct Process *proc);
264 int arch_process_clone(struct Process *retp, struct Process *proc);
265 int arch_process_exec(struct Process *proc);
267 /* The following callbacks have to be implemented in OS backend if
268 * os.h defines OS_HAVE_PROCESS_DATA. The protocol is same as for,
269 * respectively, arch_process_init, arch_process_destroy,
270 * arch_process_clone and arch_process_exec. */
271 int os_process_init(struct Process *proc);
272 void os_process_destroy(struct Process *proc);
273 int os_process_clone(struct Process *retp, struct Process *proc);
274 int os_process_exec(struct Process *proc);
276 /* The following callback has to be implemented in backend if arch.h
277 * defines ARCH_HAVE_GET_SYM_INFO.
279 * This is called for every PLT relocation R in ELF file LTE, that
280 * ltrace is about to add to it's internal representation of the
281 * program under trace.
282 * The corresponding PLT entry is for SYM_INDEX-th relocation in the file.
284 * The callback is responsible for initializing RELA and SYM.
287 * Return a negative value if this symbol (SYM_INDEX) should be ignored. */
288 int arch_get_sym_info(struct ltelf *lte, const char *filename,
289 size_t sym_index, GElf_Rela *rela, GElf_Sym *sym);
297 /* The following callback has to be implemented in backend if arch.h
298 * defines ARCH_HAVE_ADD_PLT_ENTRY.
300 * This is called for every PLT relocation R in ELF file LTE, that
301 * ltrace is about to add to a library constructed in process PROC.
302 * The corresponding PLT entry is for symbol called NAME, and it's
303 * I-th relocation in the file.
305 * If this function returns plt_default, PLT address is obtained by
306 * calling arch_plt_sym_val, and symbol is allocated. If plt_ok or
307 * plt_default are returned, the chain of symbols passed back in RET
308 * is added to library under construction. */
309 enum plt_status arch_elf_add_plt_entry(struct Process *proc, struct ltelf *lte,
310 const char *name, GElf_Rela *rela,
311 size_t i, struct library_symbol **ret);
313 /* This callback needs to be implemented if arch.h defines
314 * ARCH_HAVE_DYNLINK_DONE. It is called after the dynamic linker is
315 * done with the process startup. */
316 void arch_dynlink_done(struct Process *proc);
318 /* This callback needs to be implemented if arch.h defines
319 * ARCH_HAVE_SYMBOL_RET. It is called after a traced call returns. */
320 void arch_symbol_ret(struct Process *proc, struct library_symbol *libsym);
323 /* This callback needs to be implemented if arch.h defines
324 * ARCH_HAVE_FIND_DL_DEBUG.
325 * It is called by generic code to find the address of the dynamic
326 * linkers debug structure.
327 * DYN_ADDR holds the address of the dynamic section.
328 * If the debug area is found, return 0 and fill in the address in *RET.
329 * If the debug area is not found, return a negative value. */
330 int arch_find_dl_debug(struct Process *proc, arch_addr_t dyn_addr,
333 /* If arch.h defines ARCH_HAVE_FETCH_ARG, the following callbacks have
334 * to be implemented: arch_fetch_arg_init, arch_fetch_arg_clone,
335 * arch_fetch_arg_done, arch_fetch_arg_next and arch_fetch_retval.
336 * See fetch.h for details. */
338 /* If arch.h defines both ARCH_HAVE_FETCH_ARG and
339 * ARCH_HAVE_FETCH_PACK, the following callbacks have to be
340 * implemented: arch_fetch_param_pack_start,
341 * arch_fetch_param_pack_end. See fetch.h for details. */
343 #endif /* BACKEND_H */