usr/src/man/man3c/gettimeofday.3c

   1 '\" te
   2 .\" Copyright 1989 AT&T.  Copyright (c) 1980 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement  specifies the terms and conditions for redistribution.  Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved.
   3 .TH GETTIMEOFDAY 3C "Aug 1, 2003"
   4 .SH NAME
   5 gettimeofday, settimeofday \- get or set the date and time
   6 .SH SYNOPSIS
   7 .LP
   8 .nf
   9 #include <sys/time.h>
  10
  11 \fBint\fR \fBgettimeofday\fR(\fBstruct timeval *\fR\fItp\fR, \fBvoid *\fR\fItzp\fR);
  12 .fi
  13
  14 .LP
  15 .nf
  16 \fBint\fR \fBsettimeofday\fR(\fBstruct timeval *\fR\fItp\fR, \fBvoid *\fR\fItzp\fR);
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 The \fBgettimeofday()\fR function gets and the \fBsettimeofday()\fR function
  23 sets the system's notion of the current time. The current time is expressed in
  24 elapsed seconds and microseconds since 00:00 Universal Coordinated Time,
  25 January 1, 1970. The resolution of the system clock is hardware dependent; the
  26 time may be updated continuously or in clock ticks.
  27 .sp
  28 .LP
  29 The \fItp\fR argument points to a \fBtimeval\fR structure, which includes the
  30 following members:
  31 .sp
  32 .in +2
  33 .nf
  34 long    tv_sec;    /* seconds since Jan. 1, 1970 */
  35 long    tv_usec;   /* and microseconds */
  36 .fi
  37 .in -2
  38
  39 .sp
  40 .LP
  41 If \fItp\fR is a null pointer, the current time information is not returned or
  42 set.
  43 .sp
  44 .LP
  45 The \fBTZ\fR environment variable holds time zone information. See
  46 \fBTIMEZONE\fR(4).
  47 .sp
  48 .LP
  49 The \fItzp\fR argument to \fBgettimeofday()\fR and \fBsettimeofday()\fR is
  50 ignored.
  51 .sp
  52 .LP
  53 Only privileged processes can set the time of day.
  54 .SH RETURN VALUES
  55 .sp
  56 .LP
  57 Upon successful completion, \fB0\fR is returned.  Otherwise, \fB\(mi1\fR is
  58 returned and \fBerrno\fR is set to indicate the error.
  59 .SH ERRORS
  60 .sp
  61 .LP
  62 The \fBsettimeofday()\fR function will fail if:
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fBEINVAL\fR\fR
  67 .ad
  68 .RS 10n
  69 The structure pointed to by \fItp\fR specifies an invalid time.
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBEPERM\fR\fR
  76 .ad
  77 .RS 10n
  78 The {\fBPRIV_SYS_TIME\fR} privilege was not asserted in the effective set of
  79 the calling process.
  80 .RE
  81
  82 .sp
  83 .LP
  84 The \fBgettimeofday()\fR function will fail for 32-bit interfaces if:
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fBEOVERFLOW\fR\fR
  89 .ad
  90 .RS 13n
  91 The system time has progressed beyond 2038, thus the size of the \fBtv_sec\fR
  92 member of the \fBtimeval\fR structure pointed to by \fItp\fR is insufficient to
  93 hold the current time in seconds.
  94 .RE
  95
  96 .SH USAGE
  97 .sp
  98 .LP
  99 If the \fBtv_usec\fR member of \fItp\fR is > 500000, \fBsettimeofday()\fR
 100 rounds the seconds upward. If the time needs to be set with better than one
 101 second accuracy, call \fBsettimeofday()\fR for the seconds and then
 102 \fBadjtime\fR(2) for finer accuracy.
 103 .SH ATTRIBUTES
 104 .sp
 105 .LP
 106 See \fBattributes\fR(5) for descriptions of the following attributes:
 107 .sp
 108
 109 .sp
 110 .TS
 111 box;
 112 c | c
 113 l | l .
 114 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 115 _
 116 Interface Stability     \fBgettimeofday()\fR is Standard.
 117 _
 118 MT-Level        MT-Safe
 119 .TE
 120
 121 .SH SEE ALSO
 122 .sp
 123 .LP
 124 \fBadjtime\fR(2), \fBctime\fR(3C), \fBgethrtime\fR(3C), \fBTIMEZONE\fR(4),
 125 \fBattributes\fR(5), \fBprivileges\fR(5), \fBstandards\fR(5)