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

FreeBSD Manual Pages


home | help
DATEROUND(1)			 User Commands			  DATEROUND(1)

       dateround - Round DATE/TIME to the next occurrence of RNDSPEC.

       dateround [OPTION]...  [DATE/TIME] RNDSPEC...

       Round DATE/TIME to the next occurrence of RNDSPEC.

       If DATE/TIME is omitted a stream	of date/times is read from stdin.

       DATE/TIME can also be one of the	following specials
	 - `now'	   interpreted as the current (UTC) time stamp
	 - `time'	   the time part of the	current	(UTC) time stamp
	 - `today'	   the current date (according to UTC)
	 - `tomo[rrow]'	   tomorrow's date (according to UTC)
	 - `y[ester]day'   yesterday's date (according to UTC)

       RNDSPECs	 can  be month names (Jan, Feb,	...), weekday names (Sun, Mon,
       ...), or	days.	If  a  month  name  the	 next  date/time  relative  to
       DATE/TIME  is  returned	whose  month  part matches the value given, so
       e.`g. dateround 2012-01-01 Feb' will return 2012-02-01.	If  a  weekday
       name  is	 given,	 the next date/time after DATE/TIME whose weekday part
       matches the values given	is returned.  If a day,	the next date/time af-
       ter  DATE/TIME  whose  day  part	 matches  is  returned,	 so `dateround
       2012-01-15 1' will return 2012-02-01.

       RNDSPECs	can also be multiples of the day dividing units, e.g 1h	rounds
       to  the nearest full hour, 30m to the nearest half hour,	and 10s	to the
       next 10s	mark.

       To round	to the previous	occurrence of a	RNDSPEC	any  argument  can  be
       prefixed	 with  a  `-'  to denote that.	E.g. `dateround	2012-02-14 -1'
       will return 2012-02-01.	And `dateround 2012-02-11 -- -Sep' will	return

       Multiple	RNDSPECs are evaluated left to right.

       Note  that rounding isn't commutative, e.g.	 2012-03-01 Sat	Sep ->
       2012-09-03 vs.	    2012-03-01 Sep Sat -> 2012-09-01

       Note that non-numeric strings prefixed with a  `-'  conflict  with  the
       command line options and	a separating `--' has to be used.

       Recognized OPTIONs:

       -h, --help
	      Print help and exit

       -V, --version
	      Print version and	exit

       -q, --quiet
	      Suppress	message	about date/time	and duration parser errors and
	      fix-ups.	The default is to print	a  warning  or	the  fixed  up
	      value and	return error code 2.

       -f, --format=STRING
	      Output  format.	This can either	be a specifier string (similar
	      to strftime()'s FMT) or the name of a calendar.

       -i, --input-format=STRING...
	      Input format, can	be used	multiple times.	 Each  date/time  will
	      be  passed  to  the  input  format parsers in the	order they are
	      given, if	a date/time can	be read	successfully with a given  in-
	      put format specifier string, that	value will be used.

       -b, --base=DT
	      For underspecified input use DT as a fallback to fill in missing
	      fields.  Also used for ambiguous format specifiers  to  position
	      their  range  on the absolute time line.	Must be	a date/time in
	      ISO8601 format.  If omitted defaults to the current date/time.

       -e, --backslash-escapes
	      Enable interpretation of backslash escapes in the	output and in-
	      put format specifier strings.

       -S, --sed-mode
	      Copy parts from the input	before and after a matching date/time.
	      Note that	all occurrences	of date/times within a	line  will  be

	      Format results according to LOCALE, this would only affect month
	      and weekday names.

	      Interpret	dates on stdin or the command line as coming from  the
	      locale LOCALE, this would	only affect month and weekday names as
	      input formats have to be specified explicitly.

	      Interpret	dates on stdin or the command line as coming from  the
	      time zone	ZONE.

       -z, --zone=ZONE
	      Convert dates printed on stdout to time zone ZONE, default: UTC.

       -n, --next
	      Always round to a	different date or time.

       Format specs in dateutils are similar to	posix' strftime().

       However,	 due  to a broader range of supported calendars	dateutils must
       employ different	rules.

       Date specs:
	 %a  The abbreviated weekday name
	 %A  The full weekday name
	 %_a The weekday name shortened	to a single character (MTWRFAS)
	 %b  The abbreviated month name
	 %B  The full month name
	 %_b The month name shortened to a single character (FGHJKMNQUVXZ)
	 %c  The count of the weekday within the month (range 00 to 05)
	 %C  The count of the weekday within the year (range 00	to 53)
	 %d  The day of	the month, 2 digits (range 00 to 31)
	 %D  The day of	the year, 3 digits (range 000 to 366)
	 %F  Equivalent	to %Y-%m-%d (ymd's canonical format)
	 %g  ISO week date year	without	the century (range 00 to 99)
	 %G  ISO week date year	including the century
	 %j  Equivalent	to %D
	 %m  The month in the current calendar (range 00 to 19)
	 %Q  The quarter of the	year (range Q1 to Q4)
	 %q  The number	of the quarter (range 01 to 04)
	 %s  The number	of seconds since the Epoch.
	 %u  The weekday as number (range 01 to	07, Sunday being 07)
	 %U  The week count,  day of week is Sun (range	00 to 53)
	 %V  The ISO week count,  day of week is Mon (range 01 to 53)
	 %w  The weekday as number (range 00 to	06, Sunday being 00)
	 %W  The week count,  day of week is Mon (range	00 to 53)
	 %y  The year without a	century	(range 00 to 99)
	 %Y  The year including	the century
	 %_y The year shortened	to a single digit
	 %Z  The zone offset in	hours and minutes (HH:MM) with
	     a preceding sign (+ for offsets east of UTC, - for	offsets
	     west of UTC)

	 %Od The day as	roman numerals
	 %Om The month as roman	numerals
	 %Oy The two digit year	as roman numerals
	 %OY The year including	the century as roman numerals

	 %rs In	time systems whose Epoch is different from the unix Epoch, this
	     selects the number	of seconds since then.
	 %rY In	calendars with years that don't	coincide with the Gregorian
	     years, this selects the calendar's	year.

	 %dth  The day of the month as an ordinal number, 1st, 2nd, 3rd, etc.
	 %mth  The month of the	year as	an ordinal number, 1st,	2nd, 3rd, etc.

	 %db The business day of the month (since last month's ultimo)
	 %dB Number of business	days until this	month's	ultimo

       Time specs:
	 %H  The hour of the day using a 24h clock, 2 digits (range 00 to 23)
	 %I  The hour of the day using a 12h clock, 2 digits (range 01 to 12)
	 %M  The minute	(range 00 to 59)
	 %N  The nanoseconds (range 000000000 to 999999999)
	 %p  The string	AM or PM, noon is PM and midnight is AM.
	 %P  Like %p but in lowercase
	 %S  The  (range 00 to 60, 60 is for leap seconds)
	 %T  Equivalent	to %H:%M:%S

       General specs:
	 %n  A newline character
	 %t  A tab character
	 %%  A literal % character

	 %O  Modifier to turn decimal numbers into Roman numerals
	 %r  Modifier to turn units into real units
	 th  Suffix, read and print ordinal numbers
	 b   Suffix, treat days	as business days

       By design dates before 1601-01-01 are not supported.

       For conformity here is a	list of	calendar designators and their	corre-
       sponding	format string:
	 ymd	 %Y-%m-%d
	 ymcw	 %Y-%m-%c-%w
	 ywd	 %rY-W%V-%u
	 bizda	 %Y-%m-%db
	 lilian	    n/a
	 ldn	    n/a
	 julian	    n/a
	 jdn	    n/a

       These  designators  can	be  used  as  output  format string, moreover,
       @code{lilian}/@code{ldn}	and @code{julian}/@code{jdn} can also be  used
       as input	format string.

       Some tools ("dateadd", "dateseq") need durations	as their input.	 Dura-
       tions are generally incompatible	with input  formats  as	 specified  by
       "-i|--input-format" and (at the moment) the input syntax	is fixed.

       The  general  format  is	 "+-Nunit" where "+" or	"-" is the sign, "N" a
       number, and "unit" the unit as discussed	below.

	 s  seconds
	 m  minutes
	 h  hours
	 rs real-life seconds, as in including leap  transitions

	 d  days
	 b  business days
	 mo months
	 y  years

	 $ dateround 2012-03-01	2

	 $ dateround -n	2012-03-01 1

	 $ dateround 17:05:00 5m
	 $ dateround 17:04:00 /5m

	 $ dateround -n	17:04:00 4m
	 $ dateround -n	17:04:00 /1m

       Written by Sebastian Freundt <>

       Report bugs to:

       The full	documentation for dateround is maintained as a Texinfo manual.
       If the info and dateround programs are properly installed at your site,
       the command

	      info (dateutils)dateround

       should give you access to the complete manual.

dateutils 0.4.1			 December 2016			  DATEROUND(1)


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

home | help