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 .\" $DragonFly: src/usr.sbin/kgmon/kgmon.8,v 1.3 2006/02/17 19:40:16 swildner Exp $
  35 .\"
  36 .Dd June 6, 1993
  37 .Dt KGMON 8
  38 .Os
  39 .Sh NAME
  40 .Nm kgmon
  41 .Nd generate a dump of the operating system's profile buffers
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Op Fl Bbhpr
  45 .Op Fl M core
  46 .Op Fl N system
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility is used when profiling the operating system.
  51 When no arguments are supplied,
  52 .Nm
  53 indicates the state of operating system profiling as running,
  54 off, or not configured.
  55 (see
  56 .Xr config 8 )
  57 If the
  58 .Fl p
  59 flag is specified,
  60 .Nm
  61 extracts profile data from the operating system and produces a
  62 .Pa gmon.out
  63 file suitable for later analysis by
  64 .Xr gprof 1 .
  65 .Pp
  66 The options are as follows:
  67 .Bl -tag -width Ds
  68 .It Fl B
  69 Resume the collection of high resolution profile data.
  70 .It Fl b
  71 Resume the collection of low resolution profile data.
  72 .It Fl h
  73 Stop the collection of profile data.
  74 .It Fl p
  75 Dump the contents of the profile buffers into a
  76 .Pa gmon.out
  77 file.
  78 .It Fl r
  79 Reset all the profile buffers.
  80 If the
  81 .Fl p
  82 flag is also specified, the
  83 .Pa gmon.out
  84 file is generated before the buffers are reset.
  85 .It Fl M
  86 Extract values associated with the name list from the specified core
  87 instead of the default
  88 .Pa /dev/kmem .
  89 .It Fl N
  90 Extract the name list from the specified system instead of the
  91 default
  92 .Pa /kernel .
  93 .El
  94 .Pp
  95 If neither
  96 .Fl B
  97 nor
  98 .Fl b
  99 nor
 100 .Fl h
 101 is specified, the state of profiling collection remains unchanged.
 102 For example, if the
 103 .Fl p
 104 flag is specified and profile data is being collected,
 105 profiling will be momentarily suspended,
 106 the operating system profile buffers will be dumped,
 107 and profiling will be immediately resumed.
 108 .Pp
 109 The profile buffers should be reset when the resolution
 110 of the profile data is changed.
 111 .Sh FILES
 112 .Bl -tag -width /dev/kmemx -compact
 113 .It Pa /kernel
 114 the default system
 115 .It Pa /dev/kmem
 116 the default memory
 117 .El
 118 .Sh DIAGNOSTICS
 119 Users with only read permission on
 120 .Pa /dev/kmem
 121 cannot change the state
 122 of profiling collection.
 123 They can get a
 124 .Pa gmon.out
 125 file with the warning that the data may be
 126 inconsistent if profiling is in progress.
 127 .Sh SEE ALSO
 128 .Xr gprof 1 ,
 129 .Xr config 8
 130 .Sh HISTORY
 131 The
 132 .Nm
 133 utility appeared in
 134 .Bx 4.2 .