System Calls                                          pcsample(2)



NAME
     pcsample - program execution time profile

SYNOPSIS
     #include 

     long pcsample(uintptrt 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(SCLKTCK). 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.





SunOS 5.11          Last change: 10 Mar 1998                    1






System Calls                                          pcsample(2)



ERORS
     The pcsample() function will fail if:

     EINVAL    The value of nsamples is not valid.


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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     MT-Level                     Async-Signal-Safe           
    
     Interface Stability          Stable                      
    


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
































SunOS 5.11          Last change: 10 Mar 1998                    2