latency.tproj/latency.1

   1 .\" Copyright (c) 2000, Apple Computer, Inc.  All rights reserved.
   2 .\"
   3 .Dd March 28, 2000
   4 .Dt LATENCY 1
   5 .Os "Mac OS X"
   6 .Sh NAME
   7 .Nm latency
   8 .Nd monitors scheduling and interrupt latency
   9 .Sh SYNOPSIS
  10 .Nm latency
  11 .Op Fl rt
  12 .Op Fl c Ar code_file
  13 .Op Fl l Ar log_file
  14 .Op Fl st Ar threshold
  15 .Op Fl it Ar threshold
  16 .Op Fl s Ar sleep_in_usecs
  17 .Op Fl d Ar decrementer_in_usecs
  18 .Op Fl n Ar kernel
  19 .Sh DESCRIPTION
  20 The
  21 .Nm latency
  22 utility provides scheduling and interrupt-latency statistics.
  23 Due to the kernel tracing facility it uses to operate,
  24 the command requires root privileges.
  25 .Pp
  26 The arguments are as follows:
  27 .Bl -tag -width Ds
  28 .\" ==========
  29 .It Fl c Ar code_file
  30 When the
  31 .Fl c
  32 option is specified, it takes a path to a code file
  33 that contains the mappings for the system calls.
  34 This option overrides the default location of the system call code file,
  35 which is found in /usr/share/misc/trace.codes.
  36 .\" ==========
  37 .It Fl d Ar decrementer_in_usecs
  38 Sets the decrementer, using a value expressed in microseconds.
  39 On exit, the decrementer is set back to the system default value.
  40 .\" ==========
  41 .It Fl it Ar threshold
  42 Set the interrupt latency threshold,
  43 expressed in microseconds.
  44 If the latency exceeds this value,
  45 and a log file has been specified,
  46 a record of what occurred during this time is recorded.
  47 .\" ==========
  48 .It Fl l Ar log_file
  49 Specifies a log file that is written to when
  50 either the interrupt or scheduling latency is exceeded.
  51 .\" ==========
  52 .It Fl n Ar kernel
  53 By default,
  54 .Nm latency
  55 acts on the default /mach_kernel.
  56 This option allows you to specify an alternate booted kernel.
  57 .\" ==========
  58 .It Fl rt
  59 Sets the real-time scheduling policy.
  60 Default policy is timeshare.
  61 .\" ==========
  62 .It Fl s Ar sleep_in_usecs
  63 Sets the timer, taking an argument expressed in microseconds.
  64 The default timer is set to 1000 microseconds.
  65 .\" ==========
  66 .It Fl st Ar threshold
  67 Set the scheduler latency threshold in microseconds.
  68 If latency exceeds this, and a log file has been specified,
  69 a record of what occurred during this time is recorded.
  70 .El
  71 .Pp
  72 The data columns displayed are as follows:
  73 .Bl -tag -width LAST_PATHNAME_WAITED_FOR
  74 .It SCHEDULER
  75 The number of context switches that fall within the described delay.
  76 .It INTERRUPTS
  77 The number of interrupts that fall within the described delay.
  78 .El
  79 .Pp
  80 The
  81 .Nm latency
  82 utility is also SIGWINCH savvy, so adjusting your window geometry will change
  83 the list of delay values displayed.
  84 .Sh SAMPLE USAGE
  85 .Pp
  86 latency -rt -st 20000 -it 1000 -l /var/tmp/latency.log
  87 .Pp
  88 The
  89 .Nm latency
  90 utility will set the realtime scheduling policy.
  91 The threshold for the scheduler is set to 20000 microseconds.
  92 The threshold for interrupts is set to 1000 microseconds.
  93 Latencies that exceed these thresholds will be logged in /var/tmp/latency.log.
  94 .Sh SEE ALSO
  95 .Xr fs_usage 1 ,
  96 .Xr sc_usage 1 ,
  97 .Xr top 1