pcsample(2)

NAME

     pcsample - program execution time profile

SYNOPSIS

     #include <pcsample.h>

     long pcsample(uintptr_t samples[], long nsamples);

DESCRIPTION

     The pcsample() function provides CPU-use statistics by  pro-
     filing the amount of CPU time expended by a program.

     For profiling dynamically-linked programs  and  64-bit  pro-
     grams,  it  is  superior  to  the  profil(2) function, which
     assumes that the entire program is  contained  in  a  small,
     contiguous  segment  of the address space, divides this seg-
     ment into "bins", and on  each  clock  tick  increments  the
     counter in the bin where the program is currently executing.
     With shared libraries creating  discontinuous  program  seg-
     ments  spread  throughout the address space, and with 64-bit
     address spaces so large that the size  of  "bins"  would  be
     measured  in  megabytes, the profil() function is of limited
     value.

     The pcsample() function is passed an array samples  contain-
     ing  nsamples  pointer-sized elements. During program execu-
     tion, the kernel samples the program counter of the process,
     storing  unadulterated  values  in  the  array on each clock
     tick. The kernel stops writing to the array when it is full,
     which  occurs after nsamples / HZ seconds of process virtual
     time.  The  HZ  value  is  obtained  by  invoking  the  call
     sysconf(_SC_CLK_TCK). See sysconf(3C).

     The sampling can be stopped by a subsequent call  to  pcsam-
     ple()  with  the nsamples argument set to 0.  Like profil(),
     sampling continues across a call to fork(2), but is disabled
     by  a  call  to  one  of  the  exec family of functions (see
     exec(2)). It is also disabled if an update of the  samples[]
     array causes a memory fault.

RETURN VALUES

     The pcsample() function always returns 0 the first  time  it
     is  called.   On  subsequent calls, it returns the number of
     samples that were stored during the previous invocation.  If
     nsamples  is  invalid, it returns -1 and sets errno to indi-
     cate the error.

ERRORS

     The pcsample() function will fail if:

     EINVAL
           The value of nsamples is not valid.

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Async-Signal-Safe           |
    |_____________________________|_____________________________|
    | Interface Stability         | Stable                      |
    |_____________________________|_____________________________|

SEE ALSO

     exec(2), fork(2), profil(2), sysconf(3C), attributes(5)