Index for Section 2

Alphabetical listing for P

Bottom of page

profil(2)
NAME
  profil - Starts and stops execution profiling

SYNOPSIS
  void profil(
	  unsigned short *short_buffer,
	  unsigned int buffer_size,
	  void	*offset,
	  unsigned int scale );
  #include <sys/resource.h>

  void profil(
	  struct profil_args *args,
	  int buffer_size,
	  -1,
	  unsigned long flags);

PARAMETERS
  short_buffer
	    Points to an area of memory in the user address space. Its length
	    (in bytes) is given by the buffer_size parameter.

  buffer_size
	    Specifies the length (in bytes) of the buffer.  When offset is
	    -1, indicating that the extended profil format shown in the
	    second synopsis above is in use, the buffer_size parameter
	    indicates the number of profil_args structures in the args array.

  offset    Specifies the delta of program counter start and buffer; for
	    example, an offset of 0 (zero) implies that text begins at 0.
	    When offset is -1, the profil call is interpreted as a call to
	    profile multiple discontiguous address ranges, such as those in
	    an executable and its shared libraries.  In this type of profil
	    call, which has the format shown in the second synopsis above,
	    the buffer_size parameter indicates the number of profil_args
	    structures in the args array.

  scale	    Specifies the mapping factor between the program counter and
	    short_buffer.

  args	    When offset is -1, specifies an array of up to 64 struct
	    profil_args structures, each describing a single address range in
	    which profiling is to occur.

  flags	    Specifies flags that modify the behavior of a profil call that
	    profiles multiple discontiguous address ranges.  This argument is
	    reserved for future use and should be 0.



DESCRIPTION
  The profil() function controls execution profiling.

  The short_buffer parameter points to an area of memory whose length (in
  bytes) is given by the buffer_size parameter.	 After this call, the
  process' program counter is examined at regular intervals (for example, at
  1024 Hz).  To determine the interval for your system, use the getsysinfo(2)
  system call with GSI_CLK_TCK as the operation parameter.

  The value of the offset parameter is subtracted from the program counter,
  and the result multiplied by the scale parameter.  The corresponding
  location in the short_buffer parameter is incremented if the resulting
  number is less than the buffer_size parameter.

  The scale parameter is interpreted as an unsigned, fixed point fraction
  with 16 bits of mantissa:  0x10000  means that the address range has the
  same number of bytes as the short_buffer (that is, two bytes of instruction
  map into each short_buffer element); 0x8000 maps four bytes of instructions
  into each short_buffer element; and so on.  The special scale factor of 2
  maps all instructions onto the beginning of the short_buffer (producing a
  non-interrupting clock).

  Profiling is turned off by giving a scale parameter of either zero (0) or
  1.  Profiling is turned off when an execve() is executed.  Profiling
  remains on in both the parent and child processes after a fork.  Profiling
  is turned off if an update in the short_buffer parameter would cause a
  memory fault.

  If the process contains multiple threads, each will be independently
  sampled and the counts will reflect the sum of the samples for all of the
  threads.

  The second form of profil call allows you to profile multiple disjoint
  address ranges, such as an executable and its shared libraries.  This form
  of profil call must specify an offset of -1.	Its first argument, args,
  specifies an array of struct profil_args structures, each describing a
  single address range in which profiling is to occur.	The buffer_size
  argument indicates the number of profil_args structures in the args array.

  The members of each profil_args structure in the array pointed to by args
  are similar to the arguments in the traditional profil call, except that
  the buffer field is an array of unsigned ints instead of an array of
  unsigned shorts, and the highpc and lowpc members specify both ends of the
  address range to be profiled.	 The scale is still the ratio of bytes in the
  address range to bytes in the buffer.

  The following are the contents of a profil_args struct:

	       struct profil_args {
		       unsigned int    *buffer;
		       void	       *highpc;
		       void	       *lowpc
		       void	       *offset;
		       unsigned int    scale;
		       }

  All the address ranges specified in the array must be non-overlapping, and
  be ordered by decreasing lowpc value (that is, addresses ranges appear in
  the array in decreasing beginning address order).  As with a traditional
  profil call, profiling is turned off (for a given address range) if an
  update in the buffer (specified by the struct profil_args for that address
  range) would cause a memory fault.

  You can stop profiling started by either type of profil call by issuing the
  following command:

       profil(0,0,0,0)

  Because a traditional profil call stops all profiling started with an
  extended call, and an extended profil	 call stops all profiling started
  with a traditional call, a thread never needs to record both kinds of
  profiling activity at the same time. That is, profiling a single address
  range with a buffer of short	counters and profiling multiple address
  ranges in buffers with int counters are mutually exclusive in a given
  thread.  Although a thread can be switched from one type of profiling to
  the other with any call to the other interface and different profiling
  mechanisms can operate on separate threads simultaneously, use of a single
  profiling interface is recommended in a single application.

RELATED INFORMATION
  Functions: exec(2), fork(2), getsysinfo(2), monitor(3)

  Commands: prof(1)

Index for Section 2

Alphabetical listing for P

Top of page