date/date.1

   1 .\"     $NetBSD: date.1,v 1.22 1998/06/08 09:07:13 lukem Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1990, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" the Institute of Electrical and Electronics Engineers, Inc.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"     This product includes software developed by the University of
  20 .\"     California, Berkeley and its contributors.
  21 .\" 4. Neither the name of the University nor the names of its contributors
  22 .\"    may be used to endorse or promote products derived from this software
  23 .\"    without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  28 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  35 .\" SUCH DAMAGE.
  36 .\"
  37 .\"     @(#)date.1      8.3 (Berkeley) 4/28/95
  38 .\"
  39 .Dd January 20, 1998
  40 .Dt DATE 1
  41 .Os
  42 .Sh NAME
  43 .Nm date
  44 .Nd display or set date and time
  45 .Sh SYNOPSIS
  46 .Nm
  47 .Op Fl nu
  48 .Op Fl r Ar seconds
  49 .Op Cm + Ns Ar format
  50 .Nm ""
  51 .Ar [[[[[cc]yy]mm]dd]hh]mm[\&.ss]
  52 .Sh DESCRIPTION
  53 .Nm
  54 displays the current date and time when invoked without arguments.
  55 Providing arguments will format the date and time in a user-defined
  56 way or set the date.
  57 Only the superuser may set the date.
  58 .Pp
  59 The options are as follows:
  60 .Bl -tag -width Ds
  61 .It Fl n
  62 The utility
  63 .Xr timed 8
  64 is used to synchronize the clocks on groups of machines.
  65 By default, if
  66 timed
  67 is running,
  68 .Nm
  69 will set the time on all of the machines in the local group.
  70 The
  71 .Fl n
  72 option stops
  73 .Nm
  74 from setting the time for other than the current machine.
  75 .It Fl r
  76 Print out the date and time that is
  77 .Ar seconds
  78 from the Epoch.
  79 .It Fl u
  80 Display or set the date in
  81 .Tn UTC
  82 (universal) time.
  83 .El
  84 .Pp
  85 An operand with a leading plus (``+'') sign signals a user-defined format
  86 string which specifies the format in which to display the date and time.
  87 The format string may contain any of the conversion specifications described
  88 in the
  89 .Xr strftime 3
  90 manual page, as well as any arbitrary text.
  91 A <newline> character is always output after the characters specified by
  92 the format string.
  93 The format string for the default display is:
  94 .Bd -literal -offset indent
  95 ``%a %b %e %H:%M:%S %Z %Y''.
  96 .Ed
  97 .Pp
  98 If an operand does not have a leading plus sign, it is interpreted as
  99 a value for setting the system's notion of the current date and time.
 100 The canonical representation for setting the date and time is:
 101 .Pp
 102 .Bl -tag -width Ds -compact -offset indent
 103 .It Ar cc
 104 The first two digits of the year (the century).
 105 .It Ar yy
 106 The second two digits of the year.  If
 107 .Dq yy
 108 is specified, but
 109 .Dq cc
 110 is not, a value for
 111 .Dq yy
 112 between 69 and 99 results in a
 113 .Dq cc
 114 value of 19.  Otherwise, a
 115 .Dq cc
 116 value of 20 is used.
 117 .It Ar mm
 118 The month of the year, from 1 to 12.
 119 .It Ar dd
 120 The day of the month, from 1 to 31.
 121 .It Ar hh
 122 The hour of the day, from 0 to 23.
 123 .It Ar mm
 124 The minute of the hour, from 0 to 59.
 125 .It Ar ss
 126 The second of the minute, from 0 to 61.
 127 .El
 128 .Pp
 129 Everything but the minutes is optional.
 130 .Pp
 131 Time changes for Daylight Saving and Standard time and leap seconds
 132 and years are handled automatically.
 133 .Sh EXAMPLES
 134 The command:
 135 .Bd -literal -offset indent
 136 date ``+DATE: %m/%d/%y%nTIME: %H:%M:%S''
 137 .Ed
 138 .Pp
 139 will display:
 140 .Bd -literal -offset indent
 141 DATE: 11/21/87
 142 TIME: 13:36:16
 143 .Ed
 144 .Pp
 145 The command:
 146 .Bd -literal -offset indent
 147 date 8506131627
 148 .Ed
 149 .Pp
 150 sets the date to
 151 .Dq Li "June 13, 1985, 4:27 PM" .
 152 .Pp
 153 The command:
 154 .Bd -literal -offset indent
 155 date 1432
 156 .Ed
 157 .Pp
 158 sets the time to
 159 .Li "2:32 PM" ,
 160 without modifying the date.
 161 .Sh ENVIRONMENT VARIABLES
 162 The following environment variables affect the execution of
 163 .Nm
 164 :
 165 .Bl -tag -width TZ
 166 .It Ev TZ
 167 The timezone to use when displaying dates.
 168 See
 169 .Xr environ 7
 170 for more information.
 171 .El
 172 .Sh FILES
 173 .Bl -tag -width /var/log/messages -compact
 174 .It Pa /var/log/wtmp
 175 A record of date resets and time changes.
 176 .It Pa /var/log/messages
 177 A record of the user setting the time.
 178 .El
 179 .Sh SEE ALSO
 180 .Xr gettimeofday 2 ,
 181 .Xr strftime 3 ,
 182 .Xr utmp 5 ,
 183 .Xr timed 8
 184 .Rs
 185 .%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD"
 186 .%A R. Gusella
 187 .%A S. Zatti
 188 .Re
 189 .Sh DIAGNOSTICS
 190 Exit status is 0 on success, 1 if unable to set the date, and 2
 191 if able to set the local date, but unable to set it globally.
 192 .Pp
 193 Occasionally, when
 194 .Xr timed 8
 195 synchronizes the time on many hosts, the setting of a new time value may
 196 require more than a few seconds.
 197 On these occasions,
 198 .Nm
 199 prints:
 200 .Ql Network time being set .
 201 The message
 202 .Ql Communication error with timed
 203 occurs when the communication
 204 between
 205 .Nm
 206 and
 207 timed
 208 fails.
 209 .Sh STANDARDS
 210 The
 211 .Nm
 212 utility is expected to be compatible with
 213 .St -p1003.2 .