bin/date/date.1

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