1.\" $NetBSD: date.1,v 1.57 2024/09/17 15:25:39 kre 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 September 17, 2024 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 ajnRUu 44.Op Fl d Ar date 45.Op Fl r Ar seconds 46.Op Fl z Ar zone 47.Op Cm + Ns Ar format 48.Sm off 49.Oo 50.Oo Oo Oo Oo Oo 51.Ar CC Oc 52.Ar yy Oc 53.Ar mm Oc 54.Ar dd Oc 55.Ar HH Oc 56.Ar MM 57.Op Cm \&. Ar SS 58.Oc 59.Sm on 60.Nm 61.Op Fl ajnRu 62.Fl f Ar input_format 63.Ar new_date 64.Op Cm + Ns Ar format 65.Sh DESCRIPTION 66.Nm 67displays the current date and time when invoked without arguments. 68Providing arguments will format the date and time in a user-defined 69way or set the date. 70Only the superuser may set the date. 71.Pp 72The options are as follows: 73.Bl -tag -width Fl 74.It Fl a 75Use 76.Xr adjtime 2 77to change the local system time slowly, 78maintaining it as a monotonically increasing function. 79.Fl a 80implies 81.Fl n . 82.It Fl d Ar date 83Parse the provided human-described date and time and display the result without 84actually changing the system clock. 85(See 86.Xr parsedate 3 87for examples.) 88.It Fl f Ar input_fmt 89Use 90.Ar input_fmt 91as the format string to parse the 92.Ar new_date 93provided rather than using the default 94.Sm off 95.Oo Oo Oo Oo Oo 96.Ar CC Oc 97.Ar yy Oc 98.Ar mm Oc 99.Ar dd Oc 100.Ar HH Oc 101.Ar MM 102.Op Cm \&. Ar SS 103.Sm on 104format. 105Parsing is done using 106.Xr strptime 3 . 107.It Fl j 108Parse the provided canonical representation of date and time (described below) 109and display the result without actually changing the system clock. 110.It Fl n 111The utility 112.Xr timed 8 113is used to synchronize the clocks on groups of machines. 114By default, if 115.Xr timed 8 116is running, 117.Nm 118will set the time on all of the machines in the local group. 119The 120.Fl n 121option stops 122.Nm 123from setting the time for other than the current machine. 124.It Fl R 125Use a default display format that conforms to the date and time 126specification in RFC 5322 (Internet Message Format). 127.It Fl r Ar seconds 128Print out the date and time that is 129.Ar seconds 130from the Epoch. 131.It Fl U 132Reset the timezone used by 133.Nm 134to that which existed when it was invoked. 135This is only useful after an earlier 136.Fl u 137or 138.Fl z 139option. 140.It Fl u 141Display or set the date in UTC (universal) time. 142.It Fl z Ar zone 143Set the timezone to be used by 144.Nm 145to 146.Ar zone . 147If 148.Ar zone 149is an empty string, revert to the system's 150default timezone (ignoring any setting of 151.Ev TZ ) . 152.El 153.Pp 154Note the 155.Fl d , 156.Fl U , 157.Fl u , 158and 159.Fl z 160options are applied when encountered, hence specifying 161.Fl u 162before 163.Fl d 164will cause the 165.Ar date 166to be parsed as coordinated universal time, by default, 167whereas if 168.Fl u 169is specified after 170.Fl d 171the 172.Ar date 173will be parsed using the default timezone, then 174output will be generated in UTC. 175.Pp 176An operand with a leading plus 177.Pq Cm + 178sign signals a user-defined format 179string which specifies the format in which to display the date and time. 180The format string may contain any of the conversion specifications described 181in the 182.Xr strftime 3 183manual page, as well as any arbitrary text. 184A 185.Aq newline 186character is always output after the characters 187specified by the format string. 188The format string for the default display is: 189.Pp 190.Dl %a %b %e %H:%M:%S %Z %Y 191.Pp 192If an operand does not have a leading plus sign, it is interpreted as 193a value for setting the system's notion of the current date and time. 194The canonical representation for setting the date and time is: 195.Pp 196.Bl -tag -width Ds -compact -offset indent 197.It Ar CC 198The first two digits of the year (the century). 199.It Ar yy 200The second two digits of the year. 201If 202.Ar yy 203is specified, but 204.Ar CC 205is not, a value for 206.Ar yy 207between 69 and 99 results in a 208.Ar CC 209value of 19. 210Otherwise, a 211.Ar CC 212value of 20 is used. 213.It Ar mm 214The month of the year, from 01 to 12. 215.It Ar dd 216The day of the month, from 01 to 31. 217.It Ar HH 218The hour of the day, from 00 to 23. 219.It Ar MM 220The minute of the hour, from 00 to 59. 221.It Ar SS 222The second of the minute, from 00 to 60. 223.El 224.Pp 225Everything but the minutes is optional. 226.Pp 227Time changes for Daylight Saving and Standard Time and leap seconds 228and years are handled automatically. 229.Sh ENVIRONMENT 230The following environment variables affect the execution of 231.Nm : 232.Bl -tag -width Ev 233.It Ev TZ 234The timezone to use when displaying dates. 235See 236.Xr environ 7 237for more information. 238.El 239.Sh FILES 240.Bl -tag -width Pa -compact 241.It Pa /etc/localtime 242Symlink pointing to system's default timezone information file in 243.Pa /usr/share/zoneinfo 244directory. 245.It Pa /usr/lib/locale/ Ns Ao Ar L Ac Ns Pa /LC_TIME 246Description of time locale 247.Aq Ar L . 248.It Pa /usr/share/zoneinfo 249Time zone information directory. 250.It Pa /usr/share/zoneinfo/posixrules 251Used with POSIX-style TZ's. 252.It Pa /usr/share/zoneinfo/GMT 253For UTC leap seconds. 254.It Pa /var/log/wtmp 255A record of date resets and time changes. 256.It Pa /var/log/messages 257A record of the user setting the time. 258.El 259.Pp 260If 261.Pa /usr/share/zoneinfo/GMT 262is absent, UTC leap seconds are loaded from 263.Pa /usr/share/zoneinfo/posixrules . 264.Sh EXAMPLES 265The command: 266.Pp 267.Dl date '+DATE: %m/%d/%y%nTIME: %H:%M:%S' 268.Pp 269will display: 270.Bd -literal -offset indent 271DATE: 11/21/87 272TIME: 13:36:16 273.Ed 274.Pp 275The command: 276.Pp 277.Dl date 8506131627 278.Pp 279sets the date to 280.Dq Li "June 13, 1985, 4:27 PM" . 281.Pp 282The command: 283.Pp 284.Dl date 1432 285.Pp 286sets the time to 287.Li "2:32 PM" , 288without modifying the date. 289.Pp 290The command: 291.Pp 292.Dl date +%s 293.Pp 294prints the current time as seconds since the Epoch. 295.Pp 296The command: 297.Pp 298.Dl date -z America/Chicago -d 13:00 -z Asia/Tokyo +%H:%M 299.Pp 300indicates what the time will be in Tokyo when it is 13:00 301in Chicago. 302Any 303.Xr strftime 3 304string could be used for the output. 305The first 306.Fl z 307option can be omitted to parse the time as specified by 308.Ev TZ 309.Pq usually the local timezone , 310or the second could be replaced by 311.Fl U 312to show the parsed time in the local timezone. 313.Pp 314Either of the commands: 315.Pp 316.Dl date -u -d 1970-01-01T00:00:00 -U +%c 317.Dl date -r 0 +%c 318.Pp 319print the local time of the 320.Ux 321epoch. 322.Sh DIAGNOSTICS 323Exit status is 0 on success, 1 if unable to set the date, and 2 324if able to set the local date, but unable to set it globally. 325.Pp 326Occasionally, when 327.Xr timed 8 328synchronizes the time on many hosts, the setting of a new time value may 329require more than a few seconds. 330On these occasions, 331.Nm 332prints: 333.Ql Network time being set . 334The message 335.Ql Communication error with 336.Xr timed 8 337occurs when the communication 338between 339.Nm 340and 341.Xr timed 8 342fails. 343.Sh SEE ALSO 344.Xr adjtime 2 , 345.Xr gettimeofday 2 , 346.Xr settimeofday 2 , 347.Xr parsedate 3 , 348.Xr strftime 3 , 349.Xr utmp 5 , 350.Xr environ 7 , 351.Xr timed 8 352.Rs 353.%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD" 354.%A R. Gusella 355.%A S. Zatti 356.Re 357.Sh STANDARDS 358The 359.Nm 360utility is expected to be compatible with 361.St -p1003.2 . 362However, achieving true compatability requires running 363.Nm 364with the environment variable 365.Ev POSIXLY_CORRECT 366set, in order to parse the time string in the 367archaic format POSIX demands, rather than the 368more rational version described above. 369.Sh HISTORY 370A 371.Nm 372utility appeared in 373.At v1 . 374