path: root/man/stapprobes.signal.5.in

.\" -*- nroff -*-
.TH STAPPROBES.SIGNAL 5 @DATE@ "IBM"
.SH NAME
stapprobes.signal \- systemtap signal probe points

.\" macros
.de SAMPLE
.br
.RS
.nf
.nh
..
.de ESAMPLE
.hy
.fi
.RE
..

.SH DESCRIPTION

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.syskill

Fires when sys_kill is called to send a signal to a process.

.B Arguments:

.I pid
  pid of the recipient process

.I sig
  the signal to be sent

.P
.TP
.B signal.syskill.return

Fires when returning from sys_kill

.P
.TP
.B signal.tgkill

Fires when sys_tgkill is called to send a signal to one specific thread

.B Arguments:

.I pid
  pid of the recipient thread

.I tgid
  thread group id which the target thread should have

.I sig
  the signal to be sent

.P
.TP
.B signal.tgkill.return

Fires when returning from sys_tgkill

.P
.TP
.B signal.tkill

Fires when sys_tkill is called to send a signal to a single process.

.B Arguments:

.I pid
  pid of the recipient process

.I sig
  the signal to be sent

.P
.TP
.B signal.tkill.return

Fires when returning from sys_tkill

.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 SEE ALSO
.IR stap (1),
.IR stapprobes (5),