man3/profil.3

   1 .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Modified Fri Jun 23 01:35:19 1995 Andries Brouwer <aeb@cwi.nl>
   6 .\" (prompted by Bas V. de Bakker <bas@phys.uva.nl>)
   7 .\" Corrected (and moved to man3), 980612, aeb
   8 .TH PROFIL 3 2021-03-22 "Linux man-pages (unreleased)"
   9 .SH NAME
  10 profil \- execution time profile
  11 .SH LIBRARY
  12 Standard C library
  13 .RI ( libc ", " \-lc )
  14 .SH SYNOPSIS
  15 .nf
  16 .B #include <unistd.h>
  17 .PP
  18 .BI "int profil(unsigned short *" buf ", size_t " bufsiz ,
  19 .BI "           size_t " offset ", unsigned int " scale );
  20 .PP
  21 .fi
  22 .RS -4
  23 Feature Test Macro Requirements for glibc (see
  24 .BR feature_test_macros (7)):
  25 .RE
  26 .PP
  27 .BR profil ():
  28 .nf
  29     Since glibc 2.21:
  30 .\"             commit 266865c0e7b79d4196e2cc393693463f03c90bd8
  31         _DEFAULT_SOURCE
  32     In glibc 2.19 and 2.20:
  33         _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)
  34     Up to and including glibc 2.19:
  35         _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)
  36 .fi
  37 .SH DESCRIPTION
  38 This routine provides a means to find out in what areas your program
  39 spends most of its time.
  40 The argument
  41 .I buf
  42 points to
  43 .I bufsiz
  44 bytes of core.
  45 Every virtual 10 milliseconds, the user's program counter (PC)
  46 is examined:
  47 .I offset
  48 is subtracted and the result is multiplied by
  49 .I scale
  50 and divided by 65536.
  51 If the resulting value is less than
  52 .IR bufsiz ,
  53 then the corresponding entry in
  54 .I buf
  55 is incremented.
  56 If
  57 .I buf
  58 is NULL, profiling is disabled.
  59 .SH RETURN VALUE
  60 Zero is always returned.
  61 .SH ATTRIBUTES
  62 For an explanation of the terms used in this section, see
  63 .BR attributes (7).
  64 .ad l
  65 .nh
  66 .TS
  67 allbox;
  68 lbx lb lb
  69 l l l.
  70 Interface       Attribute       Value
  71 T{
  72 .BR profil ()
  73 T}      Thread safety   MT-Unsafe
  74 .TE
  75 .hy
  76 .ad
  77 .sp 1
  78 .SH STANDARDS
  79 Similar to a call in SVr4 (but not POSIX.1).
  80 .SH BUGS
  81 .BR profil ()
  82 cannot be used on a program that also uses
  83 .B ITIMER_PROF
  84 interval timers (see
  85 .BR setitimer (2)).
  86 .PP
  87 True kernel profiling provides more accurate results.
  88 .\" Libc 4.4 contained a kernel patch providing a system call profil.
  89 .SH SEE ALSO
  90 .BR gprof (1),
  91 .BR sprof (1),
  92 .BR setitimer (2),
  93 .BR sigaction (2),
  94 .BR signal (2)