From c74138a1e57a1e87e07b01767354332ae8739e4f Mon Sep 17 00:00:00 2001 From: Sami Kerola Date: Mon, 31 Oct 2011 22:13:24 +0100 Subject: docs: add long options to readprofile.8 Additionally align with with howto-man-page.txt Signed-off-by: Sami Kerola --- sys-utils/readprofile.8 | 148 +++++++++++++++++++++--------------------------- 1 file changed, 66 insertions(+), 82 deletions(-) (limited to 'sys-utils/readprofile.8') diff --git a/sys-utils/readprofile.8 b/sys-utils/readprofile.8 index a27043590..308dba498 100644 --- a/sys-utils/readprofile.8 +++ b/sys-utils/readprofile.8 @@ -1,105 +1,94 @@ -.TH READPROFILE "8" "May 1996" "util-linux" "System Administration" +.TH READPROFILE "8" "October 2011" "util-linux" "System Administration" .SH NAME readprofile - read kernel profiling information .SH SYNOPSIS .B readprofile .RI [ options ] - .SH VERSION This manpage documents version 2.0 of the program. - .SH DESCRIPTION - .LP The .B readprofile command uses the .B /proc/profile -information to print ascii data on standard output. -The output is +information to print ascii data on standard output. The output is organized in three columns: the first is the number of clock ticks, -the second is the name of the C function in the kernel where those many -ticks occurred, and the third is the normalized `load' of the procedure, -calculated as a ratio between the number of ticks and the length of -the procedure. The output is filled with blanks to ease readability. - -.LP -Available command line options are the following: - +the second is the name of the C function in the kernel where those +many ticks occurred, and the third is the normalized `load' of the +procedure, calculated as a ratio between the number of ticks and the +length of the procedure. The output is filled with blanks to ease +readability. +.SH OPTIONS .TP -.BI \-m " mapfile" +\fB\-m\fR, \fB\-\-mapfile\fR \fImapfile\fR Specify a mapfile, which by default is -.B /usr/src/linux/System.map. -You should specify the map file on cmdline if your current kernel isn't the -last one you compiled, or if you keep System.map elsewhere. If the name of -the map file ends with `.gz' it is decompressed on the fly. - +.BR /usr/src/linux/System.map . +You should specify the map file on cmdline if your current kernel +isn't the last one you compiled, or if you keep System.map elsewhere. +If the name of the map file ends with `.gz' it is decompressed on the +fly. .TP -.BI \-p " pro-file" +\fB\-p\fR, \fB\-\-profile\fR \fIpro-file\fR Specify a different profiling buffer, which by default is .B /proc/profile. Using a different pro-file is useful if you want to `freeze' the -kernel profiling at some time and read it later. The +kernel profiling at some time and read it later. The .B /proc/profile -file can be copied using `cat' or `cp'. There is no more support for +file can be copied using `cat' or `cp'. There is no more support for compressed profile buffers, like in .B readprofile-1.1, because the program needs to know the size of the buffer in advance. - .TP -.B \-i -Info. This makes +\fB\-i\fR, \fB\-\-info\fR +Info. This makes .B readprofile -only print the profiling step used by the kernel. -The profiling step is the resolution of the profiling buffer, and -is chosen during kernel configuration (through `make config'), -or in the kernel's command line. -If the +only print the profiling step used by the kernel. The profiling step +is the resolution of the profiling buffer, and is chosen during +kernel configuration (through `make config'), or in the kernel's +command line. If the .B \-t (terse) switch is used together with .B \-i only the decimal number is printed. - .TP -.B \-a -Print all symbols in the mapfile. By default the procedures with 0 reported -ticks are not printed. - +\fB\-a\fR, \fB\-\-all\fR +Print all symbols in the mapfile. By default the procedures with +reported ticks are not printed. .TP -.B \-b +\fB\-b\fR, \fB\-\-histbin\fR Print individual histogram-bin counts. - .TP -.B \-r -Reset the profiling buffer. This can only be invoked by root, because +\fB\-r\fR, \fB\-\-reset\fR +Reset the profiling buffer. This can only be invoked by root, +because .B /proc/profile -is readable by everybody but writable only by the superuser. However, -you can make +is readable by everybody but writable only by the superuser. +However, you can make .B readprofile setuid 0, in order to reset the buffer without gaining privileges. - .TP -.BI \-M " multiplier" +\fB\-M\fR, \fB\-\-multiplier\fR \fImultiplier\fR On some architectures it is possible to alter the frequency at which -the kernel delivers profiling interrupts to each CPU. This option allows you to -set the frequency, as a multiplier of the system clock frequency, HZ. -This is supported on i386-SMP (2.2 and 2.4 kernel) and also on sparc-SMP -and sparc64-SMP (2.4 kernel). This option also resets the profiling buffer, -and requires superuser privileges. - +the kernel delivers profiling interrupts to each CPU. This option +allows you to set the frequency, as a multiplier of the system clock +frequency, HZ. This is supported on i386-SMP (2.2 and 2.4 kernel) +and also on sparc-SMP and sparc64-SMP (2.4 kernel). This option also +resets the profiling buffer, and requires superuser privileges. .TP -.B \-v -Verbose. The output is organized in four columns and filled with blanks. -The first column is the RAM address of a kernel function, the second is -the name of the function, the third is the number of clock ticks and the -last is the normalized load. - +\fB\-v\fR, \fB\-\-verbose\fR +Verbose. The output is organized in four columns and filled with +blanks. The first column is the RAM address of a kernel function, +the second is the name of the function, the third is the number of +clock ticks and the last is the normalized load. .TP -.B \-V -Version. This makes +\fB\-V\fR, \fB\-\-version\fR +This makes .B readprofile print its version number and exit. - +.TP +\fB\-h\fR, \fB\-\-help\fR +Display help and exit. .SH EXAMPLES Browse the profiling buffer ordering by clock ticks: .nf @@ -116,7 +105,7 @@ Print only filesystem profile: readprofile | grep _ext2 .fi -Look at all the kernel information, with ram addresses" +Look at all the kernel information, with ram addresses: .nf readprofile -av | less @@ -126,43 +115,38 @@ Browse a `freezed' profile buffer for a non current kernel: readprofile -p ~/profile.freeze -m /zImage.map.gz .fi -Request profiling at 2kHz per CPU, and reset the profiling buffer +Request profiling at 2kHz per CPU, and reset the profiling buffer: .nf sudo readprofile -M 20 - .fi - .SH BUGS - .LP .B readprofile -only works with an 1.3.x or newer kernel, -because +only works with an 1.3.x or newer kernel, because .B /proc/profile changed in the step from 1.2 to 1.3 - .LP -This program only works with ELF kernels. The change for a.out kernels -is trivial, and left as an exercise to the a.out user. - +This program only works with ELF kernels. The change for a.out +kernels is trivial, and left as an exercise to the a.out user. .LP -To enable profiling, the kernel must be rebooted, because no profiling module -is available, and it wouldn't be easy to build. To enable profiling, -you can specify "profile=2" (or another number) on the kernel commandline. -The number you specify is the two-exponent used as profiling step. - +To enable profiling, the kernel must be rebooted, because no +profiling module is available, and it wouldn't be easy to build. To +enable profiling, you can specify "profile=2" (or another number) on +the kernel commandline. The number you specify is the two-exponent +used as profiling step. .LP -Profiling is disabled when interrupts are inhibited. This means that many -profiling ticks happen when interrupts are re-enabled. Watch out for -misleading information. - +Profiling is disabled when interrupts are inhibited. This means that +many profiling ticks happen when interrupts are re-enabled. Watch +out for misleading information. .SH FILES .nf /proc/profile A binary snapshot of the profiling buffer. /usr/src/linux/System.map The symbol table for the kernel. /usr/src/linux/* The program being profiled :-) .fi - .SH AVAILABILITY -The readprofile command is part of the util-linux package and is available from -ftp://ftp.kernel.org/pub/linux/utils/util-linux/. +The readprofile command is part of the util-linux package and is +available from +.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ +Linux Kernel Archive +.UE . -- cgit v1.2.3-55-g7522