projects / unix-history / blobdiff
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
BSD 4_3_Net_2 release
[unix-history] / usr / src / lib / libc / sys / getitimer.2
diff --git a/usr/src/lib/libc/sys/getitimer.2 b/usr/src/lib/libc/sys/getitimer.2
index bd702f7..e194ed9 100644 (file)
--- a/usr/src/lib/libc/sys/getitimer.2
+++ b/usr/src/lib/libc/sys/getitimer.2
@@ -1,135 +1,166 @@
-.\" Copyright (c) 1983 The Regents of the University of California.
+.\" Copyright (c) 1983, 1991 The Regents of the University of California.
 .\" All rights reserved.
 .\"
 .\" All rights reserved.
 .\"
-.\" Redistribution and use in source and binary forms are permitted provided
-.\" that: (1) source distributions retain this entire copyright notice and
-.\" comment, and (2) distributions including binaries display the following
-.\" acknowledgement:  ``This product includes software developed by the
-.\" University of California, Berkeley and its contributors'' in the
-.\" documentation or other materials provided with the distribution and in
-.\" all advertising materials mentioning features or use of this software.
-.\" Neither the name of the University nor the names of its contributors may
-.\" be used to endorse or promote products derived from this software without
-.\" specific prior written permission.
-.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
-.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
-.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
 .\"
 .\"
-.\"    @(#)getitimer.2 6.5 (Berkeley) 6/23/90
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
 .\"
 .\"
-.TH GETITIMER 2 "June 23, 1990"
-.UC 5
-.SH NAME
-getitimer, setitimer \- get/set value of interval timer
-.SH SYNOPSIS
-.nf
-.ft B
-#include <sys/time.h>
-.PP
-.ft B
-#define ITIMER_REAL    0       /* real time intervals */
-#define ITIMER_VIRTUAL 1       /* virtual time intervals */
-#define ITIMER_PROF    2       /* user and system virtual time */
-.sp
-.ft B
-getitimer(which, value)
-int which;
-struct itimerval *value;
-.PP
-.ft B
-setitimer(which, value, ovalue)
-int which;
-struct itimerval *value, *ovalue;
-.fi
-.SH DESCRIPTION
+.\"     @(#)getitimer.2        6.6 (Berkeley) 3/10/91
+.\"
+.Dd March 10, 1991
+.Dt GETITIMER 2
+.Os BSD 4.2
+.Sh NAME
+.Nm getitimer ,
+.Nm setitimer
+.Nd get/set value of interval timer
+.Sh SYNOPSIS
+.Fd #include <sys/time.h>
+.Fd #define ITIMER_REAL                0
+.Fd #define ITIMER_VIRTUAL     1
+.Fd #define ITIMER_PROF                2
+.Ft int
+.Fn getitimer "int which" "struct itimerval *value"
+.Ft int
+.Fn setitimer "int which" "struct itimerval *value" "struct itimerval *ovalue"
+.Sh DESCRIPTION
 The system provides each process with three interval timers,
 defined in
 The system provides each process with three interval timers,
 defined in
-.RI < sys/time.h >.
+.Ao Pa sys/time.h Ac .
 The
 The
-.I getitimer
+.Fn getitimer
 call returns the current value for the timer specified in
 call returns the current value for the timer specified in
-.I which
+.Fa which
 in the structure at
 in the structure at
-.IR value .
+.Fa value .
 The
 The
-.I setitimer
+.Fn setitimer
 call sets a timer to the specified
 call sets a timer to the specified
-.I value
+.Fa value
 (returning the previous value of the timer if
 (returning the previous value of the timer if
-.I ovalue
-is nonzero).
-.PP
+.Fa ovalue
+is non-nil).
+.Pp
 A timer value is defined by the 
 A timer value is defined by the 
-.I itimerval
+.Fa itimerval
 structure:
 structure:
-.PP
-.nf
-.RS
-.DT
+.Bd -literal -offset indent
 struct itimerval {
        struct  timeval it_interval;    /* timer interval */
        struct  timeval it_value;       /* current value */
 };
 struct itimerval {
        struct  timeval it_interval;    /* timer interval */
        struct  timeval it_value;       /* current value */
 };
-.RE
-.fi
-.PP
+.Ed
+.Pp
 If
 If
-.I it_value
+.Fa it_value
 is non-zero, it indicates the time to the next timer expiration. 
 If
 is non-zero, it indicates the time to the next timer expiration. 
 If
-.I it_interval
+.Fa it_interval
 is non-zero, it specifies a value to be used in reloading 
 is non-zero, it specifies a value to be used in reloading 
-.I it_value
+.Fa it_value
 when the timer expires.
 Setting 
 when the timer expires.
 Setting 
-.I it_value
+.Fa it_value
 to 0 disables a timer.  Setting 
 to 0 disables a timer.  Setting 
-.I it_interval
+.Fa it_interval
 to 0 causes a timer to be disabled after its next expiration (assuming
 to 0 causes a timer to be disabled after its next expiration (assuming
-.I it_value
+.Fa it_value
 is non-zero).
 is non-zero).
-.PP
+.Pp
 Time values smaller than the resolution of the
 system clock are rounded up to this resolution
 Time values smaller than the resolution of the
 system clock are rounded up to this resolution
-(on the VAX, 10 milliseconds).
-.PP
-The ITIMER_REAL timer decrements in real time.  A SIGALRM signal is
+(typically 10 milliseconds).
+.Pp
+The
+.Dv ITIMER_REAL
+timer decrements in real time.  A
+.Dv SIGALRM
+signal is
 delivered when this timer expires.
 delivered when this timer expires.
-.PP
-The ITIMER_VIRTUAL timer decrements in process virtual time.
-It runs only when the process is executing.  A SIGVTALRM signal
+.Pp
+The
+.Dv ITIMER_VIRTUAL
+timer decrements in process virtual time.
+It runs only when the process is executing.  A
+.Dv SIGVTALRM
+signal
 is delivered when it expires.
 is delivered when it expires.
-.PP
-The ITIMER_PROF timer decrements both in process virtual time and
+.Pp
+The
+.Dv ITIMER_PROF
+timer decrements both in process virtual time and
 when the system is running on behalf of the process.  It is designed
 to be used by interpreters in statistically profiling the execution
 of interpreted programs.
 when the system is running on behalf of the process.  It is designed
 to be used by interpreters in statistically profiling the execution
 of interpreted programs.
-Each time the ITIMER_PROF timer expires, the SIGPROF signal is
+Each time the
+.Dv ITIMER_PROF
+timer expires, the
+.Dv SIGPROF
+signal is
 delivered.  Because this signal may interrupt in-progress
 system calls, programs using this timer must be prepared to
 restart interrupted system calls.
 delivered.  Because this signal may interrupt in-progress
 system calls, programs using this timer must be prepared to
 restart interrupted system calls.
-.SH NOTES
+.Sh NOTES
 Three macros for manipulating time values are defined in
 Three macros for manipulating time values are defined in
-.RI < sys/time.h >.
-.I Timerclear
+.Ao Pa sys/time.h Ac .
+.Fa Timerclear
 sets a time value to zero,
 sets a time value to zero,
-.I timerisset
+.Fa timerisset
 tests if a time value is non-zero, and
 tests if a time value is non-zero, and
-.I timercmp
+.Fa timercmp
 compares two time values (beware that >= and <= do not
 work with this macro).
 compares two time values (beware that >= and <= do not
 work with this macro).
-.SH "RETURN VALUE
+.Sh RETURN VALUES
 If the calls succeed, a value of 0 is returned.  If an error occurs,
 If the calls succeed, a value of 0 is returned.  If an error occurs,
-the value \-1 is returned, and a more precise error code is placed
-in the global variable \fIerrno\fP.
-.SH "ERRORS
-The possible errors are:
-.TP 15
-[EFAULT]
-The \fIvalue\fP parameter specified a bad address.
-.TP 15
-[EINVAL]
-A \fIvalue\fP parameter specified a time was too large
+the value -1 is returned, and a more precise error code is placed
+in the global variable
+.Va errno .
+.Sh ERRORS
+.Fn Getitimer
+and
+.Fn setitimer
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EFAULT
+The
+.Fa value
+parameter specified a bad address.
+.It Bq Er EINVAL
+A
+.Fa value
+parameter specified a time was too large
 to be handled.
 to be handled.
-.SH "SEE ALSO"
-select(2), sigvec(2), gettimeofday(2)
+.El
+.Sh SEE ALSO
+.Xr select 2 ,
+.Xr sigvec 2 ,
+.Xr gettimeofday 2
+.Sh HISTORY
+The
+.Nm
+function call appeared in
+.Bx 4.2 .
Continuous source code history from original PDP-7 UNIX to FreeBSD 2, the first fully unencumbered FreeBSD release.