Index Index for
Section 2
Index Alphabetical
listing for P
Bottom of page Bottom of
page		 

profil(2)


NAME

  profil - Start and stop 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() 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 member is an array of unsigned int elements instead of an array
  of unsigned short elements, and the highpc and lowpc member specify both
  ends of the address range to be profiled. The scale member is still the
  ratio of bytes in the address range to bytes in the buffer.

  The following are the contents of a profil_args structure:

       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 profil_args structure for that
  address range) would cause a memory fault.

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

       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.


SEE ALSO

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

  Commands: prof(1)

Index Index for
Section 2
Index Alphabetical
listing for P
Top of page Top of
page