1.\" $NetBSD: date.1,v 1.47 2018/01/27 18:59:38 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 January 25, 2018 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 UTC (universal) time. 102.El 103.Pp 104An operand with a leading plus 105.Pq Cm + 106sign signals a user-defined format 107string which specifies the format in which to display the date and time. 108The format string may contain any of the conversion specifications described 109in the 110.Xr strftime 3 111manual page, as well as any arbitrary text. 112A <newline> character is always output after the characters 113specified by the format string. 114The format string for the default display is: 115.Bd -literal -offset indent 116%a %b %e %H:%M:%S %Z %Y 117.Ed 118.Pp 119If an operand does not have a leading plus sign, it is interpreted as 120a value for setting the system's notion of the current date and time. 121The canonical representation for setting the date and time is: 122.Pp 123.Bl -tag -width Ds -compact -offset indent 124.It Ar CC 125The first two digits of the year (the century). 126.It Ar yy 127The second two digits of the year. 128If 129.Ar yy 130is specified, but 131.Ar CC 132is not, a value for 133.Ar yy 134between 69 and 99 results in a 135.Ar CC 136value of 19. 137Otherwise, a 138.Ar CC 139value of 20 is used. 140.It Ar mm 141The month of the year, from 01 to 12. 142.It Ar dd 143The day of the month, from 01 to 31. 144.It Ar HH 145The hour of the day, from 00 to 23. 146.It Ar MM 147The minute of the hour, from 00 to 59. 148.It Ar SS 149The second of the minute, from 00 to 60. 150.El 151.Pp 152Everything but the minutes is optional. 153.Pp 154Time changes for Daylight Saving and Standard Time and leap seconds 155and years are handled automatically. 156.Sh ENVIRONMENT 157The following environment variables affect the execution of 158.Nm : 159.Bl -tag -width iTZ 160.It Ev TZ 161The timezone to use when displaying dates. 162See 163.Xr environ 7 164for more information. 165.El 166.Sh FILES 167.Bl -tag -width /usr/share/zoneinfo/posixrules -compact 168.It Pa /etc/localtime 169Symlink pointing to system's default timezone information file in 170.Pa /usr/share/zoneinfo 171directory. 172.It Pa /usr/lib/locale/<L>/LC_TIME 173Description of time locale <L>. 174.It Pa /usr/share/zoneinfo 175Time zone information directory. 176.It Pa /usr/share/zoneinfo/posixrules 177Used with POSIX-style TZ's. 178.It Pa /usr/share/zoneinfo/GMT 179For UTC leap seconds. 180.It Pa /var/log/wtmp 181A record of date resets and time changes. 182.It Pa /var/log/messages 183A record of the user setting the time. 184.El 185.Pp 186If 187.Pa /usr/share/zoneinfo/GMT 188is absent, UTC leap seconds are loaded from 189.Pa /usr/share/zoneinfo/posixrules . 190.Sh EXAMPLES 191The command: 192.Bd -literal -offset indent 193date '+DATE: %m/%d/%y%nTIME: %H:%M:%S' 194.Ed 195.Pp 196will display: 197.Bd -literal -offset indent 198DATE: 11/21/87 199TIME: 13:36:16 200.Ed 201.Pp 202The command: 203.Bd -literal -offset indent 204date 8506131627 205.Ed 206.Pp 207sets the date to 208.Dq Li "June 13, 1985, 4:27 PM" . 209.Pp 210The command: 211.Bd -literal -offset indent 212date 1432 213.Ed 214.Pp 215sets the time to 216.Li "2:32 PM" , 217without modifying the date. 218.Sh DIAGNOSTICS 219Exit status is 0 on success, 1 if unable to set the date, and 2 220if able to set the local date, but unable to set it globally. 221.Pp 222Occasionally, when 223.Xr timed 8 224synchronizes the time on many hosts, the setting of a new time value may 225require more than a few seconds. 226On these occasions, 227.Nm 228prints: 229.Ql Network time being set . 230The message 231.Ql Communication error with 232.Xr timed 8 233occurs when the communication 234between 235.Nm 236and 237.Xr timed 8 238fails. 239.Sh SEE ALSO 240.Xr adjtime 2 , 241.Xr gettimeofday 2 , 242.Xr settimeofday 2 , 243.Xr parsedate 3 , 244.Xr strftime 3 , 245.Xr utmp 5 , 246.Xr environ 7 , 247.Xr timed 8 248.Rs 249.%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD" 250.%A R. Gusella 251.%A S. Zatti 252.Re 253.Sh STANDARDS 254The 255.Nm 256utility is expected to be compatible with 257.St -p1003.2 . 258.Sh HISTORY 259A 260.Nm 261utility appeared in 262.At v1 . 263