1.\" $NetBSD: date.1,v 1.42 2012/04/06 11:36:56 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 58displays the current date and time when invoked without arguments. 59Providing arguments will format the date and time in a user-defined 60way or set the date. 61Only the superuser may set the date. 62.Pp 63The options are as follows: 64.Bl -tag -width Ds 65.It Fl a 66Use 67.Xr adjtime 2 68to change the local system time slowly, 69maintaining it as a monotonically increasing function. 70.Fl a 71implies 72.Fl n . 73.It Fl d Ar date 74Parse the provided human-described date and time and display the result without 75actually changing the system clock. 76(See 77.Xr parsedate 3 78for examples.) 79.It Fl j 80Parse the provided canonical representation of date and time (described below) 81and display the result without actually changing the system clock. 82.It Fl n 83The utility 84.Xr timed 8 85is used to synchronize the clocks on groups of machines. 86By default, if 87.Xr timed 8 88is running, 89.Nm 90will set the time on all of the machines in the local group. 91The 92.Fl n 93option stops 94.Nm 95from setting the time for other than the current machine. 96.It Fl r Ar seconds 97Print out the date and time that is 98.Ar seconds 99from the Epoch. 100.It Fl u 101Display or set the date in 102.Tn UTC 103(universal) time. 104.El 105.Pp 106An operand with a leading plus 107.Pq Cm + 108sign signals a user-defined format 109string which specifies the format in which to display the date and time. 110The format string may contain any of the conversion specifications described 111in the 112.Xr strftime 3 113manual page, as well as any arbitrary text. 114A \*[Lt]newline\*[Gt] character is always output after the characters 115specified by the format string. 116The format string for the default display is: 117.Bd -literal -offset indent 118%a %b %e %H:%M:%S %Z %Y 119.Ed 120.Pp 121If an operand does not have a leading plus sign, it is interpreted as 122a value for setting the system's notion of the current date and time. 123The canonical representation for setting the date and time is: 124.Pp 125.Bl -tag -width Ds -compact -offset indent 126.It Ar CC 127The first two digits of the year (the century). 128.It Ar yy 129The second two digits of the year. 130If 131.Ar yy 132is specified, but 133.Ar CC 134is not, a value for 135.Ar yy 136between 69 and 99 results in a 137.Ar CC 138value of 19. 139Otherwise, a 140.Ar CC 141value of 20 is used. 142.It Ar mm 143The month of the year, from 01 to 12. 144.It Ar dd 145The day of the month, from 01 to 31. 146.It Ar HH 147The hour of the day, from 00 to 23. 148.It Ar MM 149The minute of the hour, from 00 to 59. 150.It Ar SS 151The second of the minute, from 00 to 61. 152.El 153.Pp 154Everything but the minutes is optional. 155.Pp 156Time changes for Daylight Saving and Standard Time and leap seconds 157and years are handled automatically. 158.Sh ENVIRONMENT 159The following environment variables affect the execution of 160.Nm : 161.Bl -tag -width iTZ 162.It Ev TZ 163The timezone to use when displaying dates. 164See 165.Xr environ 7 166for more information. 167.El 168.Sh FILES 169.Bl -tag -width /var/log/messages -compact 170.It Pa /etc/localtime 171Symlink pointing to system's default timezone information file in 172.Pa /usr/share/zoneinfo 173directory. 174.It Pa /var/log/wtmp 175A record of date resets and time changes. 176.It Pa /var/log/messages 177A record of the user setting the time. 178.El 179.Sh EXAMPLES 180The command: 181.Bd -literal -offset indent 182date '+DATE: %m/%d/%y%nTIME: %H:%M:%S' 183.Ed 184.Pp 185will display: 186.Bd -literal -offset indent 187DATE: 11/21/87 188TIME: 13:36:16 189.Ed 190.Pp 191The command: 192.Bd -literal -offset indent 193date 8506131627 194.Ed 195.Pp 196sets the date to 197.Dq Li "June 13, 1985, 4:27 PM" . 198.Pp 199The command: 200.Bd -literal -offset indent 201date 1432 202.Ed 203.Pp 204sets the time to 205.Li "2:32 PM" , 206without modifying the date. 207.Sh DIAGNOSTICS 208Exit status is 0 on success, 1 if unable to set the date, and 2 209if able to set the local date, but unable to set it globally. 210.Pp 211Occasionally, when 212.Xr timed 8 213synchronizes the time on many hosts, the setting of a new time value may 214require more than a few seconds. 215On these occasions, 216.Nm 217prints: 218.Ql Network time being set . 219The message 220.Ql Communication error with 221.Xr timed 8 222occurs when the communication 223between 224.Nm 225and 226.Xr timed 8 227fails. 228.Sh SEE ALSO 229.Xr adjtime 2 , 230.Xr gettimeofday 2 , 231.Xr settimeofday 2 , 232.Xr parsedate 3 , 233.Xr strftime 3 , 234.Xr utmp 5 , 235.Xr environ 7 , 236.Xr timed 8 237.Rs 238.%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD" 239.%A R. Gusella 240.%A S. Zatti 241.Re 242.Sh STANDARDS 243The 244.Nm 245utility is expected to be compatible with 246.St -p1003.2 . 247