profil man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

profil(2)							     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
       Points  to  an area of memory in the user address space. Its length (in
       bytes) is given by the buffer_size parameter.  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  buf‐
       fer_size	 parameter  indicates  the number of profil_args structures in
       the args array.	Specifies the delta of program counter start and  buf‐
       fer;  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  pro‐
       file  multiple  discontiguous  address ranges, such as those in an exe‐
       cutable 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.	Specifies  the	mapping factor between the program counter and
       short_buffer.  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.  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 getsys‐
       info() 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 corre‐
       sponding 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. Profil‐
       ing 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 dis‐
       joint 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 struc‐
       ture for that address range) would cause a memory fault.

       You can stop profiling started by either type of profil() call by issu‐
       ing 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 sin‐
       gle  address range with a buffer of short counters and profiling multi‐
       ple 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 differ‐
       ent  profiling  mechanisms  can	operate on separate threads simultane‐
       ously, 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)

								     profil(2)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net