1.\" Copyright (c) 1980, 1990, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" the Institute of Electrical and Electronics Engineers, Inc. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)date.1 8.3 (Berkeley) 4/28/95 32.\" $FreeBSD: src/bin/date/date.1,v 1.72 2005/02/13 22:25:09 ru Exp $ 33.\" 34.Dd September 11, 2019 35.Dt DATE 1 36.Os 37.Sh NAME 38.Nm date 39.Nd display or set date and time 40.Sh SYNOPSIS 41.Nm 42.Op Fl jRu 43.Op Fl r Ar seconds 44.Oo 45.Fl v 46.Sm off 47.Op Cm + | - 48.Ar val Op Ar ymwdHMS 49.Sm on 50.Oc 51.Ar ... 52.Op Cm + Ns Ar output_fmt 53.Nm 54.Op Fl jnRu 55.Sm off 56.Op Oo Oo Oo Oo Ar cc Oc Ar yy Oc Ar mm Oc Ar dd Oc Ar HH 57.Ar MM Op Ar .ss 58.Sm on 59.Nm 60.Op Fl jnu 61.Fl f Ar input_fmt new_date 62.Op Cm + Ns Ar output_fmt 63.Sh DESCRIPTION 64When invoked without arguments, the 65.Nm 66utility displays the current date and time. 67Otherwise, depending on the options specified, 68.Nm 69will set the date and time or print it in a user-defined way. 70.Pp 71The 72.Nm 73utility displays the date and time read from the kernel clock. 74When used to set the date and time, 75both the kernel clock and the hardware clock are updated. 76.Pp 77Only the superuser may set the date, 78and if the system securelevel (see 79.Xr securelevel 8 ) 80is greater than 1, 81the time may not be changed by more than 1 second. 82.Pp 83The options are as follows: 84.Bl -tag -width Ds 85.It Fl f 86Use 87.Ar input_fmt 88as the format string to parse the 89.Ar new_date 90provided rather than using the default 91.Sm off 92.Oo Oo Oo Oo Oo 93.Ar cc Oc 94.Ar yy Oc 95.Ar mm Oc 96.Ar dd Oc 97.Ar HH 98.Oc Ar MM Op Ar .ss 99.Sm on 100format. 101Parsing is done using 102.Xr strptime 3 . 103.It Fl j 104Do not try to set the date. 105This allows you to use the 106.Fl f 107flag in addition to the 108.Cm + 109option to convert one date format to another. 110.It Fl n 111Obsolete flag, accepted and ignored for compatibility. 112.It Fl R 113Use RFC 2822 date and time output format. This is equivalent to use 114.Dq Li %a, %d %b %Y \&%T %z 115as 116.Ar output_fmt 117while 118.Ev LC_TIME 119is set to the 120.Dq C 121locale. 122.It Fl r Ar seconds 123Print the date and time represented by 124.Ar seconds , 125where 126.Ar seconds 127is the number of seconds since the Epoch 128(00:00:00 UTC, January 1, 1970; 129see 130.Xr time 3 ) , 131and can be specified in decimal, octal, or hex. 132.It Fl u 133Display or set the date in 134.Tn UTC 135(Coordinated Universal) time. 136.It Fl v 137Adjust (i.e., take the current date and display the result of the 138adjustment; not actually set the date) the second, minute, hour, month 139day, week day, month or year according to 140.Ar val . 141If 142.Ar val 143is preceded with a plus or minus sign, 144the date is adjusted forwards or backwards according to the remaining string, 145otherwise the relevant part of the date is set. 146The date can be adjusted as many times as required using these flags. 147Flags are processed in the order given. 148.Pp 149When setting values 150(rather than adjusting them), 151seconds are in the range 0-59, minutes are in the range 0-59, hours are 152in the range 0-23, month days are in the range 1-31, week days are in the 153range 0-6 (Sun-Sat), 154months are in the range 1-12 (Jan-Dec) 155and years are in the range 80-38 or 1980-2038. 156.Pp 157If 158.Ar val 159is numeric, one of either 160.Ar y , 161.Ar m , 162.Ar w , 163.Ar d , 164.Ar H , 165.Ar M 166or 167.Ar S 168must be used to specify which part of the date is to be adjusted. 169.Pp 170The week day or month may be specified using a name rather than a 171number. 172If a name is used with the plus 173(or minus) 174sign, the date will be put forwards 175(or backwards) 176to the next 177(previous) 178date that matches the given week day or month. 179This will not adjust the date, 180if the given week day or month is the same as the current one. 181.Pp 182When a date is adjusted to a specific value or in units greater than hours, 183daylight savings time considerations are ignored. 184Adjustments in units of hours or less honor daylight saving time. 185So, assuming the current date is March 26, 0:30 and that the DST adjustment 186means that the clock goes forward at 01:00 to 02:00, using 187.Fl v No +1H 188will adjust the date to March 26, 2:30. 189Likewise, if the date is October 29, 0:30 and the DST adjustment means that 190the clock goes back at 02:00 to 01:00, using 191.Fl v No +3H 192will be necessary to reach October 29, 2:30. 193.Pp 194When the date is adjusted to a specific value that does not actually exist 195(for example March 26, 1:30 BST 2000 in the Europe/London timezone), 196the date will be silently adjusted forwards in units of one hour until it 197reaches a valid time. 198When the date is adjusted to a specific value that occurs twice 199(for example October 29, 1:30 2000), 200the resulting timezone will be set so that the date matches the earlier of 201the two times. 202.Pp 203Adjusting the date by months is inherently ambiguous because 204a month is a unit of variable length depending on the current date. 205This kind of date adjustment is applied in the most intuitive way. 206First of all, 207.Nm 208tries to preserve the day of the month. 209If it is impossible because the target month is shorter than the present one, 210the last day of the target month will be the result. 211For example, using 212.Fl v No +1m 213on May 31 will adjust the date to June 30, while using the same option 214on January 30 will result in the date adjusted to the last day of February. 215This approach is also believed to make the most sense for shell scripting. 216Nevertheless, be aware that going forth and back by the same number of 217months may take you to a different date. 218.Pp 219Refer to the examples below for further details. 220.El 221.Pp 222An operand with a leading plus 223.Pq Sq + 224sign signals a user-defined format string 225which specifies the format in which to display the date and time. 226The format string may contain any of the conversion specifications 227described in the 228.Xr strftime 3 229manual page, as well as any arbitrary text. 230A newline 231.Pq Ql \en 232character is always output after the characters specified by 233the format string. 234The format string for the default display is 235.Dq +%+ . 236.Pp 237If an operand does not have a leading plus sign, it is interpreted as 238a value for setting the system's notion of the current date and time. 239The canonical representation for setting the date and time is: 240.Pp 241.Bl -tag -width Ds -compact -offset indent 242.It Ar cc 243Century 244(either 19 or 20) 245prepended to the abbreviated year. 246.It Ar yy 247Year in abbreviated form 248(e.g., 89 for 1989, 06 for 2006). 249.It Ar mm 250Numeric month, a number from 1 to 12. 251.It Ar dd 252Day, a number from 1 to 31. 253.It Ar HH 254Hour, a number from 0 to 23. 255.It Ar MM 256Minutes, a number from 0 to 59. 257.It Ar ss 258Seconds, a number from 0 to 61 259(59 plus a maximum of two leap seconds). 260.El 261.Pp 262Everything but the minutes is optional. 263.Pp 264Time changes for Daylight Saving Time, standard time, leap seconds, 265and leap years are handled automatically. 266.Sh ENVIRONMENT 267The following environment variables affect the execution of 268.Nm : 269.Bl -tag -width Ds 270.It Ev TZ 271The timezone to use when displaying dates. 272The normal format is a pathname relative to 273.Pa /usr/share/zoneinfo . 274For example, the command 275.Dq TZ=America/Los_Angeles date 276displays the current time in California. 277See 278.Xr environ 7 279for more information. 280.El 281.Sh FILES 282.Bl -tag -width /var/log/messages -compact 283.It Pa /var/log/wtmpx 284record of date resets and time changes 285.It Pa /var/log/messages 286record of the user setting the time 287.El 288.Sh EXIT STATUS 289The 290.Nm 291utility exits 0 on success, 1 if unable to set the date, and 2 292if able to set the local date, but unable to set it globally. 293.Sh EXAMPLES 294The command: 295.Pp 296.Dl "date ""+DATE: %Y-%m-%d%nTIME: %H:%M:%S""" 297.Pp 298will display: 299.Bd -literal -offset indent 300DATE: 1987-11-21 301TIME: 13:36:16 302.Ed 303.Pp 304In the Europe/London timezone, the command: 305.Pp 306.Dl "date -v1m -v+1y" 307.Pp 308will display: 309.Pp 310.Dl "Sun Jan 4 04:15:24 GMT 1998" 311.Pp 312where it is currently 313.Li "Mon Aug 4 04:15:24 BST 1997" . 314.Pp 315The command: 316.Pp 317.Dl "date -v1d -v3m -v0y -v-1d" 318.Pp 319will display the last day of February in the year 2000: 320.Pp 321.Dl "Tue Feb 29 03:18:00 GMT 2000" 322.Pp 323So will do the command: 324.Pp 325.Dl "date -v30d -v3m -v0y -v-1m" 326.Pp 327because there is no such date as the 30th of February. 328.Pp 329The command: 330.Pp 331.Dl "date -v1d -v+1m -v-1d -v-fri" 332.Pp 333will display the last Friday of the month: 334.Pp 335.Dl "Fri Aug 29 04:31:11 BST 1997" 336.Pp 337where it is currently 338.Li "Mon Aug 4 04:31:11 BST 1997" . 339.Pp 340The command: 341.Pp 342.Dl "date 8506131627" 343.Pp 344sets the date to 345.Dq Li "June 13, 1985, 4:27 PM" . 346.Pp 347.Dl "date ""+%Y%m%d%H%M.%S""" 348.Pp 349may be used on one machine to print out the date 350suitable for setting on another. 351.Qq ( Li "+%m%d%H%M%Y.%S" 352for use on 353.Tn Linux . ) 354.Pp 355The command: 356.Pp 357.Dl "date 1432" 358.Pp 359sets the time to 360.Li "2:32 PM" , 361without modifying the date. 362.Pp 363Finally the command: 364.Pp 365.Dl "date -j -f ""%a %b %d %T %Z %Y"" ""`date`"" ""+%s""" 366.Pp 367can be used to parse the output from 368.Nm 369and express it in Epoch time. 370.Sh SEE ALSO 371.Xr gettimeofday 2 , 372.Xr strftime 3 , 373.Xr strptime 3 , 374.Xr utmpx 5 375.Sh STANDARDS 376The 377.Nm 378utility is expected to be compatible with 379.St -p1003.2 . 380.Sh HISTORY 381A 382.Nm 383command appeared in 384.At v1 . 385