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