Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DATE(1)			FreeBSD	General	Commands Manual		       DATE(1)

     date -- display or	set date and time

     date [-nRu] [-I[FMT]] [-r filename] [-r seconds]
	  [-v[+|-]val[y|m|w|d|H|M|S]] [+output_fmt]
     date [-jnRu] [-I[FMT]] [-v[+|-]val[y|m|w|d|H|M|S]]
	  [[[[[cc]yy]mm]dd]HH]MM[.SS] [+output_fmt]
     date [-jnRu] [-I[FMT]] [-v[+|-]val[y|m|w|d|H|M|S]]	-f input_fmt new_date

     When invoked without arguments, the date utility displays the current
     date and time.  Otherwise,	depending on the options specified, date will
     set the date and time or print it in a user-defined way.

     The date utility displays the date	and time read from the kernel clock.
     When used to set the date and time, both the kernel clock and the hard-
     ware clock	are updated.

     Only the superuser	may set	the date, and if the system securelevel	(see
     securelevel(7)) is	greater	than 1,	the time may not be changed by more
     than 1 second.

     The options are as	follows:

     -f	input_fmt
	     Use input_fmt as the format string	to parse the new_date provided
	     rather than using the default [[[[[cc]yy]mm]dd]HH]MM[.SS] format.
	     Parsing is	done using strptime(3).

	     Use ISO 8601 output format.  FMT may be omitted, in which case
	     the default is date.  Valid FMT values are	date, hours, minutes,
	     and seconds.  The date and	time is	formatted to the specified
	     precision.	 When FMT is hours (or the more	precise	minutes	or
	     seconds), the ISO 8601 format includes the	timezone.

     -j	     Do	not try	to set the date.  This allows you to use the -f	flag
	     in	addition to the	+ option to convert one	date format to an-
	     other.  Note that any date	or time	components unspecified by the
	     -f	format string take their values	from the current time.

     -n	     Obsolete flag, accepted and ignored for compatibility.

     -R	     Use RFC 2822 date and time	output format.	This is	equivalent to
	     using "%a,	%d %b %Y %T %z"	as output_fmt while LC_TIME is set to
	     the "C" locale .

     -r	seconds
	     Print the date and	time represented by seconds, where seconds is
	     the number	of seconds since the Epoch (00:00:00 UTC, January 1,
	     1970; see time(3)), and can be specified in decimal, octal, or

     -r	filename
	     Print the date and	time of	the last modification of filename.

     -u	     Display or	set the	date in	UTC (Coordinated Universal) time.

     -v	[+|-]val[y|m|w|d|H|M|S]
	     Adjust (i.e., take	the current date and display the result	of the
	     adjustment; not actually set the date) the	second,	minute,	hour,
	     month day,	week day, month	or year	according to val.  If val is
	     preceded with a plus or minus sign, the date is adjusted forwards
	     or	backwards according to the remaining string, otherwise the
	     relevant part of the date is set.	The date can be	adjusted as
	     many times	as required using these	flags.	Flags are processed in
	     the order given.

	     When setting values (rather than adjusting	them), seconds are in
	     the range 0-59, minutes are in the	range 0-59, hours are in the
	     range 0-23, month days are	in the range 1-31, week	days are in
	     the range 0-6 (Sun-Sat), months are in the	range 1-12 (Jan-Dec)
	     and years are in a	limited	range depending	on the platform.

	     On	i386, years are	in the range 69-38 representing	1969-2038.  On
	     every other platform, years 0-68 are accepted and represent
	     2000-2068,	and 69-99 are accepted and represent 1969-1999.	 In
	     both cases, years between 100 and 1900 (both included) are	ac-
	     cepted and	interpreted as relative	to 1900	of the Gregorian cal-
	     endar with	a limit	of 138 on i386 and a much higher limit on ev-
	     ery other platform.  Years	starting at 1901 are also accepted,
	     and are interpreted as absolute years.

	     If	val is numeric,	one of either y, m, w, d, H, M or S must be
	     used to specify which part	of the date is to be adjusted.

	     The week day or month may be specified using a name rather	than a
	     number.  If a name	is used	with the plus (or minus) sign, the
	     date will be put forwards (or backwards) to the next (previous)
	     date that matches the given week day or month.  This will not ad-
	     just the date, if the given week day or month is the same as the
	     current one.

	     When a date is adjusted to	a specific value or in units greater
	     than hours, daylight savings time considerations are ignored.
	     Adjustments in units of hours or less honor daylight saving time.
	     So, assuming the current date is March 26,	0:30 and that the DST
	     adjustment	means that the clock goes forward at 01:00 to 02:00,
	     using -v +1H will adjust the date to March	26, 2:30.  Likewise,
	     if	the date is October 29,	0:30 and the DST adjustment means that
	     the clock goes back at 02:00 to 01:00, using -v +3H will be nec-
	     essary to reach October 29, 2:30.

	     When the date is adjusted to a specific value that	does not actu-
	     ally exist	(for example March 26, 1:30 BST	2000 in	the Eu-
	     rope/London timezone), the	date will be silently adjusted for-
	     wards in units of one hour	until it reaches a valid time.	When
	     the date is adjusted to a specific	value that occurs twice	(for
	     example October 29, 1:30 2000), the resulting timezone will be
	     set so that the date matches the earlier of the two times.

	     It	is not possible	to adjust a date to an invalid absolute	day,
	     so	using the switches -v 31d -v 12m will simply fail five months
	     of	the year.  It is therefore usual to set	the month before set-
	     ting the day; using -v 12m	-v 31d always works.

	     Adjusting the date	by months is inherently	ambiguous because a
	     month is a	unit of	variable length	depending on the current date.
	     This kind of date adjustment is applied in	the most intuitive
	     way.  First of all, date tries to preserve	the day	of the month.
	     If	it is impossible because the target month is shorter than the
	     present one, the last day of the target month will	be the result.
	     For example, using	-v +1m on May 31 will adjust the date to June
	     30, while using the same option on	January	30 will	result in the
	     date adjusted to the last day of February.	 This approach is also
	     believed to make the most sense for shell scripting.  Neverthe-
	     less, be aware that going forth and back by the same number of
	     months may	take you to a different	date.

	     Refer to the examples below for further details.

     An	operand	with a leading plus (`+') sign signals a user-defined format
     string which specifies the	format in which	to display the date and	time.
     The format	string may contain any of the conversion specifications	de-
     scribed in	the strftime(3)	manual page, as	well as	any arbitrary text.  A
     newline (`\n') character is always	output after the characters specified
     by	the format string.  The	format string for the default display is

     If	an operand does	not have a leading plus	sign, it is interpreted	as a
     value for setting the system's notion of the current date and time.  The
     canonical representation for setting the date and time is:

	   cc	   Century (either 19 or 20) prepended to the abbreviated
	   yy	   Year	in abbreviated form (e.g., 89 for 1989,	06 for 2006).
	   mm	   Numeric month, a number from	1 to 12.
	   dd	   Day,	a number from 1	to 31.
	   HH	   Hour, a number from 0 to 23.
	   MM	   Minutes, a number from 0 to 59.
	   SS	   Seconds, a number from 0 to 60 (59 plus a potential leap

     Everything	but the	minutes	is optional.

     Time changes for Daylight Saving Time, standard time, leap	seconds, and
     leap years	are handled automatically.

     The following environment variables affect	the execution of date:

     TZ	     The timezone to use when displaying dates.	 The normal format is
	     a pathname	relative to /usr/share/zoneinfo.  For example, the
	     command "TZ=America/Los_Angeles date" displays the	current	time
	     in	California.  See environ(7) for	more information.

     /var/log/utx.log	record of date resets and time changes
     /var/log/messages	record of the user setting the time

     The date utility exits 0 on success, 1 if unable to set the date, and 2
     if	able to	set the	local date, but	unable to set it globally.

     The command:

	   date	"+DATE:	%Y-%m-%d%nTIME:	%H:%M:%S"

     will display:

	   DATE: 1987-11-21
	   TIME: 13:36:16

     In	the Europe/London timezone, the	command:

	   date	-v1m -v+1y

     will display:

	   Sun Jan  4 04:15:24 GMT 1998

     where it is currently Mon Aug  4 04:15:24 BST 1997.

     The command:

	   date	-v1d -v3m -v0y -v-1d

     will display the last day of February in the year 2000:

	   Tue Feb 29 03:18:00 GMT 2000

     So	will the command:

	   date	-v3m -v30d -v0y	-v-1m

     because there is no such date as the 30th of February.

     The command:

	   date	-v1d -v+1m -v-1d -v-fri

     will display the last Friday of the month:

	   Fri Aug 29 04:31:11 BST 1997

     where it is currently Mon Aug  4 04:31:11 BST 1997.

     The command:

	   date	8506131627

     sets the date to "June 13,	1985, 4:27 PM".

	   date	"+%Y%m%d%H%M.%S"

     may be used on one	machine	to print out the date suitable for setting on
     another.  ("+%m%d%H%M%Y.%S" for use on Linux.)

     The command:

	   date	1432

     sets the time to 2:32 PM, without modifying the date.

     The command

	   TZ=America/Los_Angeles date -Iseconds -r 1533415339

     will display


     Finally the command:

	   date	-j -f "%a %b %d	%T %Z %Y" "`LC_ALL=C date`" "+%s"

     can be used to parse the output from date and express it in Epoch time.

     It	is invalid to combine the -I flag with either -R or an output format
     ("+...") operand.	If this	occurs,	date prints: `multiple output formats
     specified'	and exits with an error	status.

     locale(1),	gettimeofday(2), getutxent(3), strftime(3), strptime(3)

     R.	Gusella	and S. Zatti, TSP: The Time Synchronization Protocol for UNIX

     The date utility is expected to be	compatible with	IEEE Std 1003.2
     ("POSIX.2").  The -d, -f, -I, -j, -r, -t, and -v options are all exten-
     sions to the standard.

     The format	selected by the	-I flag	is compatible with ISO 8601.

     A date command appeared in	Version	1 AT&T UNIX.

     The -I flag was added in FreeBSD 12.0.

FreeBSD	13.0			 May 31, 2022			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help