share/doc/psd/05.sysman/1.4.t

   1 .\" Copyright (c) 1983, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)1.4.t       8.1 (Berkeley) 6/8/93
  33 .\"
  34 .sh "Timers
  35 .NH 3
  36 Real time
  37 .PP
  38 The system's notion of the current Greenwich time and the current time
  39 zone is set and returned by the call by the calls:
  40 .DS
  41 #include <sys/time.h>
  42
  43 settimeofday(tvp, tzp);
  44 struct timeval *tp;
  45 struct timezone *tzp;
  46
  47 gettimeofday(tp, tzp);
  48 result struct timeval *tp;
  49 result struct timezone *tzp;
  50 .DE
  51 where the structures are defined in \fI<sys/time.h>\fP as:
  52 .DS
  53 ._f
  54 struct timeval {
  55         long    tv_sec; /* seconds since Jan 1, 1970 */
  56         long    tv_usec;        /* and microseconds */
  57 };
  58
  59 struct timezone {
  60         int     tz_minuteswest; /* of Greenwich */
  61         int     tz_dsttime;     /* type of dst correction to apply */
  62 };
  63 .DE
  64 The precision of the system clock is hardware dependent.
  65 Earlier versions of UNIX contained only a 1-second resolution version
  66 of this call, which remains as a library routine:
  67 .DS
  68 time(tvsec)
  69 result long *tvsec;
  70 .DE
  71 returning only the tv_sec field from the \fIgettimeofday\fP call.
  72 .NH 3
  73 Interval time
  74 .PP
  75 The system provides each process with three interval timers,
  76 defined in \fI<sys/time.h>\fP:
  77 .DS
  78 ._d
  79 #define ITIMER_REAL     0       /* real time intervals */
  80 #define ITIMER_VIRTUAL  1       /* virtual time intervals */
  81 #define ITIMER_PROF     2       /* user and system virtual time */
  82 .DE
  83 The ITIMER_REAL timer decrements
  84 in real time.  It could be used by a library routine to
  85 maintain a wakeup service queue.  A SIGALRM signal is delivered
  86 when this timer expires.
  87 .PP
  88 The ITIMER_VIRTUAL timer decrements in process virtual time.
  89 It runs only when the process is executing.  A SIGVTALRM signal
  90 is delivered when it expires.
  91 .PP
  92 The ITIMER_PROF timer decrements both in process virtual time and when
  93 the system is running on behalf of the process.
  94 It is designed to be used by processes to statistically profile
  95 their execution.
  96 A SIGPROF signal is delivered when it expires.
  97 .PP
  98 A timer value is defined by the \fIitimerval\fP structure:
  99 .DS
 100 ._f
 101 struct itimerval {
 102         struct  timeval it_interval;    /* timer interval */
 103         struct  timeval it_value;       /* current value */
 104 };
 105 .DE
 106 and a timer is set or read by the call:
 107 .DS
 108 getitimer(which, value);
 109 int which; result struct itimerval *value;
 110
 111 setitimer(which, value, ovalue);
 112 int which; struct itimerval *value; result struct itimerval *ovalue;
 113 .DE
 114 The third argument to \fIsetitimer\fP specifies an optional structure
 115 to receive the previous contents of the interval timer.
 116 A timer can be disabled by specifying a timer value of 0.
 117 .PP
 118 The system rounds argument timer intervals to be not less than the
 119 resolution of its clock.  This clock resolution can be determined
 120 by loading a very small value into a timer and reading the timer back to
 121 see what value resulted.
 122 .PP
 123 The \fIalarm\fP system call of earlier versions of UNIX is provided
 124 as a library routine using the ITIMER_REAL timer.  The process
 125 profiling facilities of earlier versions of UNIX
 126 remain because
 127 it is not always possible to guarantee
 128 the automatic restart of system calls after
 129 receipt of a signal.
 130 The \fIprofil\fP call arranges for the kernel to begin gathering
 131 execution statistics for a process:
 132 .DS
 133 profil(buf, bufsize, offset, scale);
 134 result char *buf; int bufsize, offset, scale;
 135 .DE
 136 This begins sampling of the program counter, with statistics maintained
 137 in the user-provided buffer.