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