bin/date/date.1

   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 February 16, 2022
  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/d
  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 .Nm
  64 .Op Fl jnu
  65 .Op Fl I Ns Op Ar FMT
  66 .Op Fl f Ar input_fmt
  67 .Op Fl r Ar ...
  68 .Op Fl v/d Ar ...
  69 .Op Ar new_date
  70 .Sh DESCRIPTION
  71 When invoked without arguments, the
  72 .Nm
  73 utility displays the current date and time.
  74 Otherwise, depending on the options specified,
  75 .Nm
  76 will set the date and time or print it in a user-defined way.
  77 .Pp
  78 The
  79 .Nm
  80 utility displays the date and time read from the kernel clock.
  81 When used to set the date and time,
  82 both the kernel clock and the hardware clock are updated.
  83 .Pp
  84 Only the superuser may set the date,
  85 and if the system securelevel (see
  86 .Xr securelevel 8 )
  87 is greater than 1,
  88 the time may not be changed by more than 1 second.
  89 .Pp
  90 The options are as follows:
  91 .Bl -tag -width Ds
  92 .It Fl f
  93 Use
  94 .Ar input_fmt
  95 as the format string to parse the
  96 .Ar new_date
  97 provided rather than using the default
  98 .Sm off
  99 .Oo Oo Oo Oo Oo
 100 .Ar cc Oc
 101 .Ar yy Oc
 102 .Ar mm Oc
 103 .Ar dd Oc
 104 .Ar HH
 105 .Oc Ar MM Op Ar .ss
 106 .Sm on
 107 format.
 108 Parsing is done using
 109 .Xr strptime 3 .
 110 .It Fl I Ns Op Ar FMT
 111 Use
 112 .St -iso8601
 113 output format.
 114 .Ar FMT
 115 may be omitted, in which case the default is
 116 .Sq date .
 117 Valid
 118 .Ar FMT
 119 values are
 120 .Sq date ,
 121 .Sq hours ,
 122 .Sq minutes ,
 123 and
 124 .Sq seconds .
 125 The date and time is formatted to the specified precision.
 126 The
 127 .St -iso8601
 128 format includes the timezone, except when
 129 .Ar FMT
 130 is
 131 .Sq date .
 132 .It Fl j
 133 Do not try to set the date.
 134 This allows you to use the
 135 .Fl f
 136 flag in addition to the
 137 .Cm +
 138 option to convert one date format to another.
 139 .It Fl n
 140 Obsolete flag, accepted and ignored for compatibility.
 141 .It Fl R
 142 Use RFC 2822 date and time output format. This is equivalent to use
 143 .Dq Li %a, %d %b %Y \&%T %z
 144 as
 145 .Ar output_fmt
 146 while
 147 .Ev LC_TIME
 148 is set to the
 149 .Dq C
 150 locale.
 151 .It Fl r Ar seconds
 152 Print the date and time represented by
 153 .Ar seconds ,
 154 where
 155 .Ar seconds
 156 is the number of seconds since the Epoch
 157 (00:00:00 UTC, January 1, 1970;
 158 see
 159 .Xr time 3 ) ,
 160 and can be specified in decimal, octal, or hex.
 161 .It Fl u
 162 Display or set the date in
 163 .Tn UTC
 164 (Coordinated Universal) time.
 165 .It Fl d
 166 For some compatibility with gnu date, the
 167 .Fl d
 168 option is an alias for the
 169 .Fl v
 170 option.
 171 In addition to the formats already supported, we now support
 172 .Ar +/-Ndays
 173 (seconds, minutes, hours, months, years, and abbreviations of same),
 174 .Ar next ... ,
 175 .Ar last ...
 176 several month, day, and year arrangements, h:m[:s], and a few other
 177 things.
 178 Not all of these can be combined with prefixes and there is still a lot
 179 of missing support for gnu date compatibility.
 180 In particular the handling of TZ= timezone specifications is mis-applied
 181 and support for the "Z" suffix is missing.
 182 .It Fl v
 183 Adjust (i.e., take the current date and display the result of the
 184 adjustment; not actually set the date) the second, minute, hour, month
 185 day, week day, month or year according to
 186 .Ar val .
 187 If
 188 .Ar val
 189 is preceded with a plus or minus sign,
 190 the date is adjusted forwards or backwards according to the remaining string,
 191 otherwise the relevant part of the date is set.
 192 The date can be adjusted as many times as required using these flags.
 193 Flags are processed in the order given.
 194 .Pp
 195 When setting values
 196 (rather than adjusting them),
 197 seconds are in the range 0-59, minutes are in the range 0-59, hours are
 198 in the range 0-23, month days are in the range 1-31, week days are in the
 199 range 0-6 (Sun-Sat),
 200 months are in the range 1-12 (Jan-Dec)
 201 and years are in the range 80-38 or 1980-2038.
 202 .Pp
 203 If
 204 .Ar val
 205 is numeric, one of either
 206 .Ar y ,
 207 .Ar m ,
 208 .Ar w ,
 209 .Ar d ,
 210 .Ar H ,
 211 .Ar M
 212 or
 213 .Ar S
 214 must be used to specify which part of the date is to be adjusted.
 215 .Pp
 216 The week day or month may be specified using a name rather than a
 217 number.
 218 If a name is used with the plus
 219 (or minus)
 220 sign, the date will be put forwards
 221 (or backwards)
 222 to the next
 223 (previous)
 224 date that matches the given week day or month.
 225 This will not adjust the date,
 226 if the given week day or month is the same as the current one.
 227 .Pp
 228 When a date is adjusted to a specific value or in units greater than hours,
 229 daylight savings time considerations are ignored.
 230 Adjustments in units of hours or less honor daylight saving time.
 231 So, assuming the current date is March 26, 0:30 and that the DST adjustment
 232 means that the clock goes forward at 01:00 to 02:00, using
 233 .Fl v No +1H
 234 will adjust the date to March 26, 2:30.
 235 Likewise, if the date is October 29, 0:30 and the DST adjustment means that
 236 the clock goes back at 02:00 to 01:00, using
 237 .Fl v No +3H
 238 will be necessary to reach October 29, 2:30.
 239 .Pp
 240 When the date is adjusted to a specific value that does not actually exist
 241 (for example March 26, 1:30 BST 2000 in the Europe/London timezone),
 242 the date will be silently adjusted forwards in units of one hour until it
 243 reaches a valid time.
 244 When the date is adjusted to a specific value that occurs twice
 245 (for example October 29, 1:30 2000),
 246 the resulting timezone will be set so that the date matches the earlier of
 247 the two times.
 248 .Pp
 249 Adjusting the date by months is inherently ambiguous because
 250 a month is a unit of variable length depending on the current date.
 251 This kind of date adjustment is applied in the most intuitive way.
 252 First of all,
 253 .Nm
 254 tries to preserve the day of the month.
 255 If it is impossible because the target month is shorter than the present one,
 256 the last day of the target month will be the result.
 257 For example, using
 258 .Fl v No +1m
 259 on May 31 will adjust the date to June 30, while using the same option
 260 on January 30 will result in the date adjusted to the last day of February.
 261 This approach is also believed to make the most sense for shell scripting.
 262 Nevertheless, be aware that going forth and back by the same number of
 263 months may take you to a different date.
 264 .Pp
 265 Refer to the examples below for further details.
 266 .El
 267 .Pp
 268 An operand with a leading plus
 269 .Pq Sq +
 270 sign signals a user-defined format string
 271 which specifies the format in which to display the date and time.
 272 The format string may contain any of the conversion specifications
 273 described in the
 274 .Xr strftime 3
 275 manual page, as well as any arbitrary text.
 276 A newline
 277 .Pq Ql \en
 278 character is always output after the characters specified by
 279 the format string.
 280 The format string for the default display is
 281 .Dq +%+ .
 282 .Pp
 283 If an operand does not have a leading plus sign, it is interpreted as
 284 a value for setting the system's notion of the current date and time.
 285 The canonical representation for setting the date and time is:
 286 .Pp
 287 .Bl -tag -width Ds -compact -offset indent
 288 .It Ar cc
 289 Century
 290 (either 19 or 20)
 291 prepended to the abbreviated year.
 292 .It Ar yy
 293 Year in abbreviated form
 294 (e.g., 89 for 1989, 06 for 2006).
 295 .It Ar mm
 296 Numeric month, a number from 1 to 12.
 297 .It Ar dd
 298 Day, a number from 1 to 31.
 299 .It Ar HH
 300 Hour, a number from 0 to 23.
 301 .It Ar MM
 302 Minutes, a number from 0 to 59.
 303 .It Ar ss
 304 Seconds, a number from 0 to 61
 305 (59 plus a maximum of two leap seconds).
 306 .El
 307 .Pp
 308 Everything but the minutes is optional.
 309 .Pp
 310 Time changes for Daylight Saving Time, standard time, leap seconds,
 311 and leap years are handled automatically.
 312 .Sh ENVIRONMENT
 313 The following environment variables affect the execution of
 314 .Nm :
 315 .Bl -tag -width Ds
 316 .It Ev TZ
 317 The timezone to use when displaying dates.
 318 The normal format is a pathname relative to
 319 .Pa /usr/share/zoneinfo .
 320 For example, the command
 321 .Dq TZ=America/Los_Angeles date
 322 displays the current time in California.
 323 See
 324 .Xr environ 7
 325 for more information.
 326 .El
 327 .Sh FILES
 328 .Bl -tag -width /var/log/messages -compact
 329 .It Pa /var/log/wtmpx
 330 record of date resets and time changes
 331 .It Pa /var/log/messages
 332 record of the user setting the time
 333 .El
 334 .Sh EXIT STATUS
 335 The
 336 .Nm
 337 utility exits 0 on success, 1 if unable to set the date, and 2
 338 if able to set the local date, but unable to set it globally.
 339 .Sh EXAMPLES
 340 The command:
 341 .Pp
 342 .Dl "date ""+DATE: %Y-%m-%d%nTIME: %H:%M:%S"""
 343 .Pp
 344 will display:
 345 .Bd -literal -offset indent
 346 DATE: 1987-11-21
 347 TIME: 13:36:16
 348 .Ed
 349 .Pp
 350 In the Europe/London timezone, the command:
 351 .Pp
 352 .Dl "date -v1m -v+1y"
 353 .Pp
 354 will display:
 355 .Pp
 356 .Dl "Sun Jan  4 04:15:24 GMT 1998"
 357 .Pp
 358 where it is currently
 359 .Li "Mon Aug  4 04:15:24 BST 1997" .
 360 .Pp
 361 The command:
 362 .Pp
 363 .Dl "date -v1d -v3m -v0y -v-1d"
 364 .Pp
 365 will display the last day of February in the year 2000:
 366 .Pp
 367 .Dl "Tue Feb 29 03:18:00 GMT 2000"
 368 .Pp
 369 So will do the command:
 370 .Pp
 371 .Dl "date -v30d -v3m -v0y -v-1m"
 372 .Pp
 373 because there is no such date as the 30th of February.
 374 .Pp
 375 The command:
 376 .Pp
 377 .Dl "date -v1d -v+1m -v-1d -v-fri"
 378 .Pp
 379 will display the last Friday of the month:
 380 .Pp
 381 .Dl "Fri Aug 29 04:31:11 BST 1997"
 382 .Pp
 383 where it is currently
 384 .Li "Mon Aug  4 04:31:11 BST 1997" .
 385 .Pp
 386 The command:
 387 .Pp
 388 .Dl "date 8506131627"
 389 .Pp
 390 sets the date to
 391 .Dq Li "June 13, 1985, 4:27 PM" .
 392 .Pp
 393 .Dl "date ""+%Y%m%d%H%M.%S"""
 394 .Pp
 395 may be used on one machine to print out the date
 396 suitable for setting on another.
 397 .Qq ( Li "+%m%d%H%M%Y.%S"
 398 for use on
 399 .Tn Linux . )
 400 .Pp
 401 The command:
 402 .Pp
 403 .Dl "date 1432"
 404 .Pp
 405 sets the time to
 406 .Li "2:32 PM" ,
 407 without modifying the date.
 408 .Pp
 409 The command:
 410 .Pp
 411 .Dl "TZ=America/Los_Angeles date -Iseconds -r 1533415339"
 412 .Pp
 413 will display
 414 .Pp
 415 .Dl "2018-08-04T13:42:19-07:00"
 416 .Pp
 417 Finally the command:
 418 .Pp
 419 .Dl "date -j -f ""%a %b %d %T %Z %Y"" ""`date`"" ""+%s"""
 420 .Pp
 421 can be used to parse the output from
 422 .Nm
 423 and express it in Epoch time.
 424 .Sh SEE ALSO
 425 .Xr gettimeofday 2 ,
 426 .Xr strftime 3 ,
 427 .Xr strptime 3 ,
 428 .Xr utmpx 5
 429 .Sh STANDARDS
 430 The
 431 .Nm
 432 utility is expected to be compatible with
 433 .St -p1003.2 .
 434 .Pp
 435 The format selected by the
 436 .Fl I
 437 flag is compatible with
 438 .St -iso8601 .
 439 .Sh HISTORY
 440 A
 441 .Nm
 442 command appeared in
 443 .At v1 .
 444 .Pp
 445 The
 446 .Fl I
 447 flag was added in
 448 .Fx 12.0
 449 and
 450 .Dx 6.3 .