bin/date/date.1

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