unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



profil(2)							    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 <&lt;sys/resource.h>&gt;

  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 indi-
	    cates 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 loca-
  tion 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 sam-
  pled 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 sin-
  gle 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)