usr.sbin/kgmon/kgmon.8

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)kgmon.8     8.1 (Berkeley) 6/6/93
  29 .\" $FreeBSD: src/usr.sbin/kgmon/kgmon.8,v 1.7.2.4 2003/03/11 21:13:50 trhodes Exp $
  30 .\" $DragonFly: src/usr.sbin/kgmon/kgmon.8,v 1.4 2008/09/02 11:50:46 matthias Exp $
  31 .\"
  32 .Dd September 2, 2008
  33 .Dt KGMON 8
  34 .Os
  35 .Sh NAME
  36 .Nm kgmon
  37 .Nd generate a dump of the operating system's profile buffers
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Op Fl Bbhpr
  41 .Op Fl M core
  42 .Op Fl N system
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 utility is used when profiling the operating system.
  47 When no arguments are supplied,
  48 .Nm
  49 indicates the state of operating system profiling as running,
  50 off, or not configured.
  51 (see
  52 .Xr config 8 )
  53 If the
  54 .Fl p
  55 flag is specified,
  56 .Nm
  57 extracts profile data from the operating system and produces a
  58 .Pa gmon.out
  59 file suitable for later analysis by
  60 .Xr gprof 1 .
  61 .Pp
  62 The options are as follows:
  63 .Bl -tag -width Ds
  64 .It Fl B
  65 Resume the collection of high resolution profile data.
  66 .It Fl b
  67 Resume the collection of low resolution profile data.
  68 .It Fl h
  69 Stop the collection of profile data.
  70 .It Fl p
  71 Dump the contents of the profile buffers into a
  72 .Pa gmon.out
  73 file.
  74 .It Fl r
  75 Reset all the profile buffers.
  76 If the
  77 .Fl p
  78 flag is also specified, the
  79 .Pa gmon.out
  80 file is generated before the buffers are reset.
  81 .It Fl M
  82 Extract values associated with the name list from the specified core
  83 instead of the default
  84 .Pa /dev/kmem .
  85 .It Fl N
  86 Extract the name list from the specified system instead of the
  87 default
  88 .Pa /boot/kernel .
  89 .El
  90 .Pp
  91 If neither
  92 .Fl B
  93 nor
  94 .Fl b
  95 nor
  96 .Fl h
  97 is specified, the state of profiling collection remains unchanged.
  98 For example, if the
  99 .Fl p
 100 flag is specified and profile data is being collected,
 101 profiling will be momentarily suspended,
 102 the operating system profile buffers will be dumped,
 103 and profiling will be immediately resumed.
 104 .Pp
 105 The profile buffers should be reset when the resolution
 106 of the profile data is changed.
 107 .Sh FILES
 108 .Bl -tag -width /dev/kmemx -compact
 109 .It Pa /boot/kernel
 110 the default system
 111 .It Pa /dev/kmem
 112 the default memory
 113 .El
 114 .Sh DIAGNOSTICS
 115 Users with only read permission on
 116 .Pa /dev/kmem
 117 cannot change the state
 118 of profiling collection.
 119 They can get a
 120 .Pa gmon.out
 121 file with the warning that the data may be
 122 inconsistent if profiling is in progress.
 123 .Sh SEE ALSO
 124 .Xr gprof 1 ,
 125 .Xr config 8
 126 .Sh HISTORY
 127 The
 128 .Nm
 129 utility appeared in
 130 .Bx 4.2 .