From bfa3d6708bb6ddcb27155ab3cc904b9c85a60e95 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Mon, 16 Mar 2009 14:21:52 +1000 Subject: fixed format of non-grabbable comments (for Tapset Reference Guide), added tapsetdescription for man page generator (in development) --- tapset/signal.stp | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'tapset/signal.stp') diff --git a/tapset/signal.stp b/tapset/signal.stp index 8fb6fe57..bde9160c 100644 --- a/tapset/signal.stp +++ b/tapset/signal.stp @@ -8,13 +8,15 @@ // Public License (GPL); either version 2, or (at your option) any // later version. // -// Note : Since there are so many signals sent to processes at any give -// point, it's better to filter the information according to the -// requirements. For example, filter only for a particular signal -// (if sig==2) or filter only for a particular process -// (if pid_name==stap). // - +// +// This family of probe points is used to probe signal activities. +// Since there are so many signals sent to processes at any give +// point, it's advisable to filter the information according to the +// requirements. For example, filter only for a particular signal +// (if sig==2) or filter only for a particular process +// (if pid_name==stap). +// /** * probe signal.send- Fires when a system call or kernel function sends a signal to a process. -- cgit From ecbe2ee5c2aef01d0c99256a5c9adbf2e8db16d0 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Mon, 16 Mar 2009 15:32:54 +1000 Subject: minor edit --- tapset/signal.stp | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'tapset/signal.stp') diff --git a/tapset/signal.stp b/tapset/signal.stp index bde9160c..a2ebe145 100644 --- a/tapset/signal.stp +++ b/tapset/signal.stp @@ -11,11 +11,10 @@ // // // This family of probe points is used to probe signal activities. -// Since there are so many signals sent to processes at any give -// point, it's advisable to filter the information according to the +// Since there are so many signals sent to processes at any given +// point, it is advisable to filter the information according to the // requirements. For example, filter only for a particular signal -// (if sig==2) or filter only for a particular process -// (if pid_name==stap). +// (if sig==2) or for a particular process (if pid_name==stap). // /** -- cgit From 810f66c21bc8e4b1403ed57eeb4b9bfdea6ef5b9 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Mon, 16 Mar 2009 16:01:28 +1000 Subject: minor edits to ensure uniformity in manpage generator --- tapset/signal.stp | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'tapset/signal.stp') diff --git a/tapset/signal.stp b/tapset/signal.stp index a2ebe145..265fd04e 100644 --- a/tapset/signal.stp +++ b/tapset/signal.stp @@ -130,24 +130,24 @@ probe _signal.send.part3 = kernel.function("send_sigqueue") * Possible __group_send_sig_info and * specific_send_sig_info return values are as follows; * - * 0 - The signal is sucessfully sent to a process, + * 0 -- The signal is sucessfully sent to a process, * which means that * <1> the signal was ignored by the receiving process, * <2> this is a non-RT signal and the system already has one queued, and * <3> the signal was successfully added to the sigqueue of the receiving process. * - * -EAGAIN - The sigqueue of the receiving process is + * -EAGAIN -- The sigqueue of the receiving process is * overflowing, the signal was RT, and the signal was sent by a user using something other * than kill() * * Possible send_group_sigqueue and * send_sigqueue return values are as follows; * - * 0 - The signal was either sucessfully added into the + * 0 -- The signal was either sucessfully added into the * sigqueue of the receiving process, or a SI_TIMER entry is already * queued (in which case, the overrun count will be simply incremented). * - * 1 - The signal was ignored by the receiving process. + * 1 -- The signal was ignored by the receiving process. * * * -1 - (send_sigqueue only) The task was marked -- cgit From 5d369d06fa39e4769fb3364ba29f588f3d995c24 Mon Sep 17 00:00:00 2001 From: William Cohen Date: Mon, 16 Mar 2009 11:27:59 -0400 Subject: Edit signal.stp documentation comments. --- tapset/signal.stp | 174 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 105 insertions(+), 69 deletions(-) (limited to 'tapset/signal.stp') diff --git a/tapset/signal.stp b/tapset/signal.stp index 265fd04e..711ee70f 100644 --- a/tapset/signal.stp +++ b/tapset/signal.stp @@ -18,7 +18,7 @@ // /** - * probe signal.send- Fires when a system call or kernel function sends a signal to a process. + * probe signal.send - Signal being sent to a process * Arguments: * @sig: The number of the signal * @sig_name: A string representation of the signal @@ -28,7 +28,8 @@ * @task: A task handle to the signal recipient * @sinfo: The address of siginfo struct * @shared: Indicates whether the signal is shared by the thread group - * @send2queue- Indicates whether the signal is sent to an existing sigqueue + * @send2queue: Indicates whether the signal is sent to an existing + * sigqueue * @name: The name of the function used to send out the signal * * Context: @@ -115,14 +116,14 @@ probe _signal.send.part3 = kernel.function("send_sigqueue") } /** - * probe signal.send.return - Fires when a signal sent to a process returns. + * probe signal.send.return - Signal being sent to a process completed * @retstr: The return value to either __group_send_sig_info, - * specific_send_sig_info, or send_sigqueue. - * Refer to the Description of this probe for more information about the return - * values of each function call. + * specific_send_sig_info, + * or send_sigqueue * @shared: Indicates whether the sent signal is shared by the thread group. - * @send2queue: Indicates whether the sent signal was sent to an existing sigqueue - * @name: The name of the function used to send out the signal. + * @send2queue: Indicates whether the sent signal was sent to an + * existing sigqueue + * @name: The name of the function used to send out the signal * * Context: * The signal's sender. (correct?) @@ -233,7 +234,7 @@ probe _signal.send.part3.return = kernel.function("send_sigqueue").return } /** - * probe signal.checkperm - Fires when a permission check is performed on a sent signal + * probe signal.checkperm - Check being performed on a sent signal * @sig: The number of the signal * @sig_name: A string representation of the signal * @sig_pid: The PID of the process receiving the signal @@ -241,7 +242,8 @@ probe _signal.send.part3.return = kernel.function("send_sigqueue").return * @si_code: Indicates the signal type * @task: A task handle to the signal recipient * @sinfo: The address of the siginfo structure - * @name: Name of the probe point; default value is signal.checkperm + * @name: Name of the probe point; default value is + * signal.checkperm */ probe signal.checkperm = kernel.function("check_kill_permission") { @@ -262,6 +264,12 @@ probe signal.checkperm = kernel.function("check_kill_permission") si_code="SI_USER or SI_TIMER or SI_ASYNCIO" } +/** + * probe signal.checkperm.return - Check performed on a sent signal completed + * @name: Name of the probe point; default value is + * signal.checkperm + * @retstr: Return value as a string + */ probe signal.checkperm.return = kernel.function("check_kill_permission").return { name = "signal.checkperm" @@ -270,15 +278,15 @@ probe signal.checkperm.return = kernel.function("check_kill_permission").return /** - * probe signal.wakeup - Wakes up a sleeping process, making it ready for new active signals - * @sig_pid: The PID of the process you wish to wake - * @pid_name: Name of the process you wish to wake - * @resume: Indicates whether to wake up a task in a STOPPED or - * TRACED state + * probe signal.wakeup - Sleeping process being wakened for signal + * @sig_pid: The PID of the process to wake + * @pid_name: Name of the process to wake + * @resume: Indicates whether to wake up a task in a + * STOPPED or TRACED state * @state_mask: A string representation indicating the mask - * of task states you wish to wake. Possible values are TASK_INTERRUPTIBLE, - * TASK_STOPPED, TASK_TRACED, - * and TASK_INTERRUPTIBLE. + * of task states to wake. Possible values are + * TASK_INTERRUPTIBLE, TASK_STOPPED, + * TASK_TRACED, and TASK_INTERRUPTIBLE. */ probe signal.wakeup = kernel.function("signal_wake_up") { @@ -294,8 +302,7 @@ probe signal.wakeup = kernel.function("signal_wake_up") /** - * probe signal.check_ignored - Fires when a system call or kernel function checks whether a - * signal was ignored or not + * probe signal.check_ignored - Checking to see signal is ignored * @sig_pid: The PID of the process receiving the signal * @pid_name: Name of the process receiving the signal * @sig: The number of the signal @@ -309,6 +316,12 @@ probe signal.check_ignored = kernel.function("sig_ignored") sig_name = _signal_name($sig) } +/** + * probe signal.check_ignored.return - Check to see signal is ignored completed + * @name: Name of the probe point; default value is + * signal.checkperm + * @retstr: Return value as a string + */ probe signal.check_ignored.return = kernel.function("sig_ignored").return ? { name = "sig_ignored" @@ -334,8 +347,7 @@ probe signal.handle_stop = kernel.function("handle_stop_signal") /** - * probe signal.force_segv - Fires when a system call, kernel function, or process sent a - * SIGSEGV as a result of problems it encountered while handling a received signal + * probe signal.force_segv - Forcing send of SIGSEGV * @sig_pid: The PID of the process receiving the signal * @pid_name: Name of the process receiving the signal * @sig: The number of the signal @@ -361,6 +373,12 @@ probe _signal.force_segv.part2 = kernel.function("force_sigsegv_info") ? sig_name = _signal_name($sig) } +/** + * probe signal.force_segv.return - Forcing send of SIGSEGV complete + * @name: Name of the probe point; default value is + * force_sigsegv + * @retstr: Return value as a string + */ probe signal.force_segv.return = kernel.function("force_sigsegv").return, kernel.function("force_sigsegv_info").return ? @@ -371,9 +389,8 @@ probe signal.force_segv.return = /** - * probe signal.syskill - Fires when the kernel function sys_kill - * sends a kill signal to a process - * @pid: The PID of the process receiving the kill signal + * probe signal.syskill - Sending kill signal to a process + * @pid: The PID of the process receiving the signal * @sig: The specific signal sent to the process */ probe signal.syskill = syscall.kill @@ -381,33 +398,43 @@ probe signal.syskill = syscall.kill sig_name = _signal_name($sig) } +/** + * probe signal.syskill.return - Sending kill signal completed + */ probe signal.syskill.return = syscall.kill.return { } + /** - * probe signal.sys_tkill - Fires when tkill sends a kill signal - * to a process that is part of a thread group + * probe signal.sys_tkill - Sending a kill signal to a thread * @pid: The PID of the process receiving the kill signal * @sig: The specific signal sent to the process + * @sig_name: The specific signal sent to the process + * * The tkill call is analogous to kill(2), * except that it also allows a process within a specific thread group to - * be targetted. Such processes are targetted through their unique thread IDs (TID). + * be targetted. Such processes are targetted through their unique + * thread IDs (TID). */ probe signal.systkill = syscall.tkill { sig_name = _signal_name($sig) } +/** + * probe signal.systkill.return - Sending kill signal to a thread completed + */ probe signal.systkill.return = syscall.tkill.return { } /** - * probe signal.sys_tgkill - Fires when the kernel function tgkill - * sends a kill signal to a specific thread group + * probe signal.sys_tgkill - Sending kill signal to a thread group * @pid: The PID of the thread receiving the kill signal * @tgid: The thread group ID of the thread receiving the kill signal * @sig: The specific kill signal sent to the process + * @sig_name: A string representation of the signal + * * The tgkill call is similar to tkill, * except that it also allows the caller to specify the thread group ID of * the thread to be signalled. This protects against TID reuse. @@ -417,12 +444,15 @@ probe signal.systgkill = syscall.tgkill sig_name = _signal_name($sig) } +/** + * probe signal.sys_tgkill.return - Sending kill signal to a thread group completed + */ probe signal.systgkill.return = syscall.tgkill.return { } /** - * probe signal.send_sig_queue - Fires when a signal is queued to a process + * probe signal.send_sig_queue - Queuing a signal to a process * @sig: The queued signal * @sig_name: A string representation of the signal * @sig_pid: The PID of the process to which the signal is queued @@ -440,6 +470,10 @@ probe signal.send_sig_queue = sigqueue_addr = $q } +/** + * probe signal.send_sig_queue.return - Queuing a signal to a process completed + * @retstr: Return value as a string + */ probe signal.send_sig_queue.return = kernel.function("send_sigqueue").return, kernel.function("send_group_sigqueue").return ? @@ -449,25 +483,25 @@ probe signal.send_sig_queue.return = /** - * probe signal.pending - Fires when the SIGPENDING system call is used; - * this normally occurs when the do_sigpending kernel function is executed - * @sigset_add: The address of the user-space signal set (sigset_t) - * @sigset_size: The size of the user-space signal set. - * - * Synopsis: - * long do_sigpending(void __user *set, unsigned long sigsetsize) + * probe signal.pending - Examining pending signal + * @sigset_add: The address of the user-space signal set + * (sigset_t) + * @sigset_size: The size of the user-space signal set * * This probe is used to examine a set of signals pending for delivery - * to a specific thread. + * to a specific thread. This normally occurs when the + * do_sigpending kernel function is executed. */ -// long do_sigpending(void __user *set, unsigned long sigsetsize) - probe signal.pending = kernel.function("do_sigpending") { sigset_add=$set sigset_size=$sigsetsize } +/** + * probe signal.pending.return - Examination of pending signal completed + * @retstr: Return value as a string + */ probe signal.pending.return = kernel.function("do_sigpending").return { retstr = returnstr(1) @@ -475,22 +509,17 @@ probe signal.pending.return = kernel.function("do_sigpending").return /** - * probe signal.handle - Fires when the signal handler is invoked + * probe signal.handle - Signal handler being invoked * @sig: The signal number that invoked the signal handler * @sinfo: The address of the siginfo table - * @sig_code: The si_code value of the siginfo signal - * @ka_addr: The address of the k_sigaction table associated with the signal + * @sig_code: The si_code value of the + * siginfo signal + * @ka_addr: The address of the k_sigaction table + * associated with the signal * @oldset_addr: The address of the bitmask array of blocked signals * @regs: The address of the kernel-mode stack area * @sig_mode: Indicates whether the signal was a user-mode or kernel-mode signal - * - * Synopsis: - * static int handle_signal(unsigned long sig, siginfo_t *info, struct k_sigaction *ka, - * sigset_t *oldset, struct pt_regs * regs) */ -//static int handle_signal(unsigned long sig, siginfo_t *info, struct k_sigaction *ka, -// sigset_t *oldset, struct pt_regs * regs) - probe signal.handle = kernel.function("handle_signal") { sig = $sig @@ -509,6 +538,10 @@ probe signal.handle = kernel.function("handle_signal") sig_mode = "Kernel Mode Signal" } +/** + * probe signal.handle.return - Signal handler invocation completed + * @retstr: Return value as a string + */ probe signal.handle.return = kernel.function("handle_signal").return ? { retstr = returnstr(1) @@ -516,11 +549,12 @@ probe signal.handle.return = kernel.function("handle_signal").return ? /** - * probe signal.do_action - Initiates a trace when a thread is about to examine - * and change a signal action + * probe signal.do_action - Examining or changing a signal action * @sig: The signal to be examined/changed - * @sigact_addr: The address of the new sigaction struct associated with the signal - * @oldsigact_addr: The address of the old sigaction struct associated with the signal + * @sigact_addr: The address of the new sigaction + * struct associated with the signal + * @oldsigact_addr: The address of the old sigaction + * struct associated with the signal * @sa_handler: The new handler of the signal * @sa_mask: The new mask of the signal */ @@ -536,6 +570,10 @@ probe signal.do_action = kernel.function("do_sigaction") } } +/** + * probe signal.do_action.return - Examining or changing a signal action completed + * @retstr: Return value as a string + */ probe signal.do_action.return = kernel.function("do_sigaction").return { retstr = returnstr(1) @@ -555,16 +593,17 @@ function __get_action_mask:long(act:long) %{ /* pure */ /** - * probe signal.procmask - Initiates a trace when a thread is about to examine and change blocked signals + * probe signal.procmask - Examining or changing blocked signals * @how: Indicates how to change the blocked signals; possible values are * SIG_BLOCK=0 (for blocking signals), * SIG_UNBLOCK=1 (for unblocking signals), and * SIG_SETMASK=2 for setting the signal mask. - * @sigset_addr: The address of the signal set (sigset_t) to be implemented - * @oldsigset_addr: The old address of the signal set (sigset_t) - * @sigset: The actual value to be set for sigset_t (correct?) - * Synopsis: - * int sigprocmask(int how, sigset_t *set, sigset_t *oldset) + * @sigset_addr: The address of the signal set (sigset_t) + * to be implemented + * @oldsigset_addr: The old address of the signal set + * (sigset_t) + * @sigset: The actual value to be set for sigset_t + * (correct?) */ probe signal.procmask = kernel.function("sigprocmask") { @@ -592,16 +631,13 @@ probe signal.procmask.return = kernel.function("sigprocmask").return /** - * probe signal.flush - Fires when all pending signals for a task are flushed + * probe signal.flush - Flusing all pending signals for a task * @task: The task handler of the process performing the flush - * @sig_pid: The PID of the process associated with the task performing the flush - * @pid_name: The name of the process associated with the task performing the flush - * - * Synopsis: - * void flush_signals(struct task_struct *t) + * @sig_pid: The PID of the process associated with the task + * performing the flush + * @pid_name: The name of the process associated with the task + * performing the flush */ -//void flush_signals(struct task_struct *t) - probe signal.flush = kernel.function("flush_signals") { task = $t -- cgit From 8391565d6f48a6fea6f5ea29dcc8790125039278 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Wed, 18 Mar 2009 15:29:19 +1000 Subject: minor edits --- tapset/signal.stp | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) (limited to 'tapset/signal.stp') diff --git a/tapset/signal.stp b/tapset/signal.stp index 711ee70f..e8470a9c 100644 --- a/tapset/signal.stp +++ b/tapset/signal.stp @@ -31,7 +31,7 @@ * @send2queue: Indicates whether the signal is sent to an existing * sigqueue * @name: The name of the function used to send out the signal - * + * * Context: * The signal's sender. * @@ -124,10 +124,10 @@ probe _signal.send.part3 = kernel.function("send_sigqueue") * @send2queue: Indicates whether the sent signal was sent to an * existing sigqueue * @name: The name of the function used to send out the signal - * + * * Context: * The signal's sender. (correct?) - * + * * Possible __group_send_sig_info and * specific_send_sig_info return values are as follows; * @@ -139,19 +139,18 @@ probe _signal.send.part3 = kernel.function("send_sigqueue") * * -EAGAIN -- The sigqueue of the receiving process is * overflowing, the signal was RT, and the signal was sent by a user using something other - * than kill() - * + * than kill(). + * * Possible send_group_sigqueue and * send_sigqueue return values are as follows; - * + * * 0 -- The signal was either sucessfully added into the * sigqueue of the receiving process, or a SI_TIMER entry is already * queued (in which case, the overrun count will be simply incremented). * * 1 -- The signal was ignored by the receiving process. * - * - * -1 - (send_sigqueue only) The task was marked + * -1 -- (send_sigqueue only) The task was marked * exiting, allowing * posix_timer_event to redirect it to the group * leader. * -- cgit