document signal tapsets into stapprobes.5.in

some changes to arguments and comments of signal tapset

1 files changed, 424 insertions, 0 deletions

diff --git a/stapprobes.5.in b/stapprobes.5.in
index 552c5382..38314f8b 100644
--- a/stapprobes.5.in
+++ b/stapprobes.5.in
@@ -732,6 +732,430 @@ Fires when returning from udp.disconnect
 .I ret
   error code (0: no error)
 
+.SS SIGNAL
+
+This family of probe points is used to probe signal activities.
+It contains the following probe points:
+
+.P
+.TP
+.B signal.send
+
+Fires when a signal is sent to a process
+
+.B Arguments:
+
+.I sig
+  signal number
+
+.I sig_name
+  a string representation of the signal
+
+.I sig_pid
+  pid of the signal recipient process
+
+.I pid_name
+  name of the signal recipient process
+
+.I si_code
+  indicates the signal type
+
+.I task
+  a task handle to the signal recipient
+
+.I sinfo
+  the address of siginfo struct
+
+.I shared
+  indicates whether this signal is shared by the thread group
+
+.I send2queue
+  indicates whether this signal is sent to an existing sigqueue
+
+.I name
+  name of the function used to send out this signal
+
+.P
+.TP
+.B signal.send.return
+
+Fires when return from sending a signal
+
+.B Arguments:
+
+.I retstr
+  the return value
+
+  Return values for "__group_send_sig_info" and "specific_send_sig_info"
+
+.RS
+.RS
+- return 0 if the signal is sucessfully sent to a process, 
+which means the following:
+
+<1> the signal is ignored by receiving process
+
+<2> this is a non-RT signal and we already have one queued
+
+<3> the signal is successfully added into the sigqueue of receiving process
+
+- return -EAGAIN if the sigqueue is overflow the signal was RT and sent 
+by user using something other than kill()
+.RE
+
+  Return values for ""send_group_sigqueue"
+
+.RS
+- return 0 if the signal is either sucessfully added into the
+sigqueue of receiving process or a SI_TIMER entry is already
+queued so just increment the overrun count
+
+- return 1 if this signal is ignored by receiving process
+.RE
+
+  Return values for "send_sigqueue"
+
+.RS
+- return 0 if the signal is either sucessfully added into the
+sigqueue of receiving process or a SI_TIMER entry is already
+queued so just increment the overrun count
+
+- return 1 if this signal is ignored by receiving process
+
+- return -1 if the task is marked exiting, so posix_timer_event
+can redirect it to the group leader
+.RE
+
+.I shared
+  indicates whether this signal is shared by the thread group
+
+.I send2queue
+  indicates whether this signal is sent to an existing sigqueue
+
+.I name
+  name of the function used to send out this signal
+
+
+.RE
+.RE
+.P
+.TP
+.B signal.checkperm
+
+Fires when check permissions for sending the signal
+
+.B Arguments:
+
+.I sig
+  the number of the signal
+
+.I sig_name
+  a string representation of the signal
+
+.I sig_pid
+  pid of the signal recipient process
+
+.I pid_name
+  name of the signal recipient process
+
+.I si_code
+  indicates the signal type
+
+.I task
+  a task handle to the signal recipient
+
+.I sinfo
+  the address of siginfo struct
+
+.I name
+  name of the probe point, is set to "signal.checkperm"
+
+.P
+.TP
+.B signal.checkperm.return
+
+Fires when return from permissions check for sending a signal
+
+.B Arguments:
+
+.I retstr
+  the return value
+
+.I name
+  name of the probe point, is set to "signal.checkperm"
+
+.P
+.TP
+.B signal.wakeup
+
+Fires when wake up the process for new active signals
+
+.B Arguments:
+
+.I sig_pid
+  pid of the process to be woke up
+
+.I pid_name
+  name of the process to be woke up
+
+.I resume
+  indicate whether to wake up a task in STOPPED or TRACED state
+
+.I state_mask
+  a string representation indicate the mask of task states 
+that can be woken. Possible values are 
+(TASK_INTERRUPTIBLE|TASK_STOPPED|TASK_TRACED) and
+TASK_INTERRUPTIBLE.
+
+.P
+.TP
+.B signal.check_ignored
+
+Fires when check whether the signal is ignored or not
+
+.B Arguments:
+
+.I sig_pid
+  pid of the signal recipient process
+
+.I pid_name
+  name of the signal recipient process
+
+.I sig
+  the signal to be checked
+
+.I sig_name
+  name of the signal
+
+.P
+.TP
+.B signal.check_ignored.return
+
+Fires when return from signal.check_ignored
+
+.B Arguments:
+
+.I retstr
+  return value. 0 indicate the current signal isn't ignored.
+
+.P
+.TP
+.B signal.force_segv
+
+Forces SIGSEGV when there are some issues while handling 
+signals for the process 
+
+.B Arguments:
+
+.I sig_pid
+  pid of the signal recipient process
+
+.I pid_name
+  name of the signal recipient process
+
+.I sig
+  the signal being handled
+
+.I sig_name
+  name of this signal
+
+.P
+.TP
+.B signal.force_segv.return
+
+Fires when return from signal.force_segv
+
+.B Arguments:
+
+.I retstr
+  return value. Always return 0
+
+.P
+.TP
+.B signal.send_sig_queue
+
+Fires when queue a signal to a process
+
+.B Arguments:
+
+.I sig
+  the signal to be queued
+
+.I sig_name
+  name of this signal
+
+.I sig_pid
+  pid of the process to which the signal is queued
+
+.I pid_name
+  name of the process  to which the signal is queued
+
+.I sigqueue_addr
+  address of the signal queue
+
+.P
+.TP
+.B signal.send_sig_queue.return
+
+Fires when return from signal.send_sig_queue
+
+.B Arguments:
+
+.I retstr
+  return value
+
+.P
+.TP
+.B signal.pending
+
+Fires when examine the set of signals that are 
+pending for delivery to the calling thread
+
+.B Arguments:
+
+.I sigset_add
+  address of user space sigset_t
+
+.I sigset_size
+  sigset size
+
+.P
+.TP
+.B signal.pending.return
+
+Fires when return from signal.pending
+
+.B Arguments:
+
+.I retstr
+  return value
+
+.P
+.TP
+.B signal.handle
+
+Fires when invoking the signal handler
+
+.B Arguments:
+
+.I sig
+  signal number
+
+.I sig_name
+  signal name
+
+.I sinfo
+  address of siginfo struct
+
+.I sig_code
+  the si_code of siginfo
+
+.I ka_addr
+  Address of the k_sigaction struct associated with the signal
+
+.I oldset_addr
+  Address of a bit mask array of blocked signals
+
+.I sig_mode
+  indicates whether the signal is a User Mode or Kernel mode Signal
+
+.P
+.TP
+.B signal.handle.return
+
+Fires when return from signal.handle
+
+.B Arguments:
+
+.I retstr
+  return value of handle_signal()
+
+.P
+.TP
+.B signal.do_action
+
+Fires by calling thread to examine and change a signal action
+ 
+.B Arguments:
+
+.I sig
+  signal number
+
+.I sigact_addr
+  address of the new sigaction struct associated with the signal
+
+.I oldsigact_addr
+  address of a previous sigaction struct associated with the signal
+
+.I sa_handler
+  the new handler of the signal
+
+.I sa_mask
+  the new mask of the signal
+
+.P
+.TP
+.B signal.do_action.return
+
+Fires when return from signal.do_action
+
+.B Arguments:
+
+.I retstr
+  return value of do_sigaction()
+
+.P
+.TP
+.B signal.procmask
+
+Fires by calling thread to examine and change blocked signals
+
+.B Arguments:
+
+.I how
+  indicates how to change the blocked signals. 
+  Possible values are:
+    SIG_BLOCK=0 for blocking signals
+    SIG_UNBLOCK=1 for unblocking signals
+    SIG_SETMASK=2 for setting the signal mask
+
+.I sigset_addr
+  address of sigset_t to be set
+
+.I oldsigset_addr
+  address of the old sigset_t
+
+.I sigset
+  the actual sigset to be set
+
+.P
+.TP
+.B signal.procmask.return
+
+Fires when return from signal.procmask
+
+.B Arguments:
+
+.I retstr
+  return value of sigprocmask()
+
+.P
+.TP
+.B signal.flush
+
+Fires when flush all pending signals for a task
+
+.B Arguments:
+
+.I task
+  the task handler of the process
+
+.I sig_pid
+  pid of the task
+
+.I pid_name
+  name of the task
+
 .SH EXAMPLES
 .PP
 Here are some example probe points, defining the associated events.