LOCKSTAT(8) | System Manager's Manual | LOCKSTAT(8)

# NAME

`lockstat` — display kernel locking statistics

# SYNOPSIS

`lockstat` | [`-cdeflMmpstx`] [`-b` nbuf] [`-E` event] [`-F` func] [`-L` lock] [`-N` nlist] [`-o` file] [`-T` type] command ...

# DESCRIPTION

The `lockstat` command enables system wide tracing of kernel lock events, executes the specified command, and when finished reports statistics to the user.

Tracing may be ended early by sending `SIGINT` (Ctrl-C) to the process being executed by lockstat.

The `lockstat` pseudo-device driver must be present in the kernel, and the `lockstat` command may only be used by the root user.

The options are as follows:

`-b` nbuf
  Adjust the number of trace buffers allocated by the kernel to nbuf.
`-c`
  Report percentage of total events by count, and sort the output by number of events. The default is to key on event timings.
`-d`
  Disable lockstat. This is useful when a program crashed leaving the lockstat kernel driver enabled.
`-E` event
  Limit tracing to one type of event. Use the `-e` option to list valid events.
`-e`
  List valid event types for the `-E` option and exit.
`-F` func
  Limit tracing to locking operations performed within the specified function. func must be the name of a valid function in the kernel.
`-f`
  Trace only by calling functions; do not report on individual locks.
`-L` lock
  Limit tracing to one lock. lock may either be the name of a lock object in the kernel, or a kernel virtual address.
`-l`
  Trace only by lock; do not report on calling functions.
`-M`
  Merge lock addresses within unique objects.
`-m`
  Merge call sites within unique functions.
`-N` nlist
  Extract symbol information from the nlist file.
`-o` file
  Send output to the file named by file, instead of the standard output (the default).
`-p`
  Show the average number of events and time spent per CPU. The default is to show the total values. May be used in conjunction with the `-s` option.
`-s`
  Show the average number of events per second, and the average time spent per second. The default is to show the total values.
`-T` type
  Limit tracing to one type of lock. Use the `-t` option to list valid lock types.
`-t`
  List valid lock types for the `-T` option and exit.
`-x`
  Summarize events, and do not report on lock types.

# FILES

/dev/lockstat
  `lockstat` control device
/dev/ksyms
  namelist

# EXAMPLES

    # lockstat -L uvm_pageqlock sleep 10
    Elapsed time: 10.01 seconds.

    -- Adaptive mutex spin

    Total%  Count   Time/ms          Lock                       Caller
    ------ ------- --------- ---------------------- ------------------------------
    100.00    1281      0.78 uvm_pageqlock          <all>
     39.81     385      0.31 uvm_pageqlock          uvm_fault_internal+11cc
     30.98     358      0.24 uvm_pageqlock          uvm_fault_internal+bb1
     28.06     522      0.22 uvm_pageqlock          uvm_anfree+132
      0.51       5      0.00 uvm_pageqlock          ubc_fault+28f
      0.20       4      0.00 uvm_pageqlock          uvm_fault_internal+12b6
      0.18       2      0.00 uvm_pageqlock          uao_detach_locked+58
      0.11       2      0.00 uvm_pageqlock          uvm_fault_internal+7d5
      0.08       2      0.00 uvm_pageqlock          ufs_balloc_range+160
      0.07       1      0.00 uvm_pageqlock          uvm_fault_internal+107b

# DIAGNOSTICS

lockstat: incompatible lockstat interface version

  The kernel device driver does not match the version of the `lockstat` command.

lockstat: overflowed available kernel trace buffers

  Increase the number of buffers using the `-b` option.

lockstat: ioctl: Invalid argument

  The number of trace buffers is outside the minimum and maximum bounds set by the kernel.

# SEE ALSO

ps(1), systat(1), vmstat(1), iostat(8), pstat(8)

# HISTORY

The `lockstat` command appeared in NetBSD 4.0.

March 6, 2013 | NetBSD 11.0