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