"Fossies" - the Fresh Open Source Software Archive

Member "dateutils-0.4.6/info/datediff.mand" (19 Mar 2019, 11975 Bytes) of package /linux/privat/dateutils-0.4.6.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "datediff.mand": 0.4.5_vs_0.4.6.

    1 .\" auto generated by yuck -*- nroff -*-
    2 .TH DATEDIFF "1" "March 2019" "dateutils 0.4.6" "User Commands"
    3 .SH NAME
    4 datediff - Compute duration from DATE/TIME (the reference date/time) to the other
    5 .SH SYNOPSIS
    6 .B datediff
    7 [\fIOPTION\fR]... 
    8 DATE/TIME \fI\fR[\fIDATE/TIME\fR]\fR...
    9 .SH DESCRIPTION
   10 Compute duration from DATE/TIME (the reference date/time) to the other
   11 DATE/TIMEs given and print the result as duration.
   12 If the other DATE/TIMEs are omitted read them from stdin.
   13 
   14 DATE/TIME can also be one of the following specials
   15   - `now'           interpreted as the current (UTC) time stamp
   16   - `time'          the time part of the current (UTC) time stamp
   17   - `today'         the current date (according to UTC)
   18   - `tomo[rrow]'    tomorrow's date (according to UTC)
   19   - `y[ester]day'   yesterday's date (according to UTC)
   20 
   21 Note: The output format of durations (specified via -f) takes all format
   22 specifiers into account, i.e. specifying %M and %S for example prints the
   23 duration in minutes and seconds, whereas specifying %S only prints the duration
   24 in seconds.
   25 
   26 See section `The refinement rule' in datediff(1).
   27 
   28 .PP
   29 
   30 Recognized \fIOPTION\fRs:
   31 .TP
   32 .B   \fB-h\fR, \fB--help
   33 Print help and exit
   34 .TP
   35 .B   \fB-V\fR, \fB--version
   36 Print version and exit
   37 .TP
   38 .B   \fB-q\fR, \fB--quiet
   39 Suppress message about date/time and duration
   40 parser errors and fix-ups.
   41 The default is to print a warning or the
   42 fixed up value and return error code 2.
   43 Also see -S|--skip-illegal to output an empty
   44 line instead of leaving out the line altogether.
   45 .TP
   46 .B   \fB-S\fR, \fB--skip-illegal
   47 Deprecated, use -E|--empty-mode.
   48 .TP
   49 .B   \fB-E\fR, \fB--empty-mode
   50 Output empty lines as placeholder for illegal
   51 input, i.e. parser errors or date/times that
   52 cannot be subtracted.
   53 .TP
   54 .B   \fB-f\fR, \fB--format\fR=\fISTRING
   55 Output format.  This can either be a specifier
   56 string (similar to strftime()'s FMT) or the name
   57 of a calendar.
   58 .TP
   59 .B   \fB-i\fR, \fB--input-format\fR=\fISTRING\fR...
   60 Input format, can be used multiple times.
   61 Each date/time will be passed to the input
   62 format parsers in the order they are given, if a
   63 date/time can be read successfully with a given
   64 input format specifier string, that value will
   65 be used.
   66 .TP
   67 .B   \fB-b\fR, \fB--base\fR=\fIDT
   68 For underspecified input use DT as a fallback to
   69 fill in missing fields.  Also used for ambiguous
   70 format specifiers to position their range on the
   71 absolute time line.
   72 Must be a date/time in ISO8601 format.
   73 If omitted defaults to the current date/time.
   74 .TP
   75 .B   \fB-e\fR, \fB--backslash-escapes
   76 Enable interpretation of backslash escapes in the
   77 output and input format specifier strings.
   78 .TP
   79 .B       \fB--from-locale\fR=\fILOCALE
   80 Interpret dates on stdin or the command line as
   81 coming from the locale LOCALE, this would only
   82 affect month and weekday names as input formats
   83 have to be specified explicitly.
   84 .TP
   85 .B       \fB--from-zone\fR=\fIZONE
   86 Interpret dates on stdin or the command line as
   87 coming from the time zone ZONE.
   88 .SH FORMAT SPECS
   89 .PP
   90 Format specs in dateutils are similar to posix' strftime().
   91 .PP
   92 However, due to a broader range of supported calendars dateutils must
   93 employ different rules.
   94 .PP
   95 Date specs:
   96 .nf
   97   %a  The abbreviated weekday name
   98   %A  The full weekday name
   99   %_a The weekday name shortened to a single character (MTWRFAS)
  100   %b  The abbreviated month name
  101   %B  The full month name
  102   %_b The month name shortened to a single character (FGHJKMNQUVXZ)
  103   %c  The count of the weekday within the month (range 00 to 05)
  104   %C  The count of the weekday within the year (range 00 to 53)
  105   %d  The day of the month, 2 digits (range 00 to 31)
  106   %D  The day of the year, 3 digits (range 000 to 366)
  107   %F  Equivalent to %Y-%m-%d (ymd's canonical format)
  108   %g  ISO week date year without the century (range 00 to 99)
  109   %G  ISO week date year including the century
  110   %j  Equivalent to %D
  111   %m  The month in the current calendar (range 00 to 19)
  112   %Q  The quarter of the year (range Q1 to Q4)
  113   %q  The number of the quarter (range 01 to 04)
  114   %s  The number of seconds since the Epoch.
  115   %u  The weekday as number (range 01 to 07, Sunday being 07)
  116   %U  The week count,  day of week is Sun (range 00 to 53)
  117   %V  The ISO week count,  day of week is Mon (range 01 to 53)
  118   %w  The weekday as number (range 00 to 06, Sunday being 00)
  119   %W  The week count,  day of week is Mon (range 00 to 53)
  120   %y  The year without a century (range 00 to 99)
  121   %Y  The year including the century
  122   %_y The year shortened to a single digit
  123   %Z  The zone offset in hours and minutes (HH:MM) with
  124       a preceding sign (+ for offsets east of UTC, - for offsets
  125       west of UTC)
  126 .fi
  127 .PP
  128 .nf
  129   %Od The day as roman numerals
  130   %Om The month as roman numerals
  131   %Oy The two digit year as roman numerals
  132   %OY The year including the century as roman numerals
  133 .fi
  134 .PP
  135 .nf
  136   %rs In time systems whose Epoch is different from the unix Epoch, this
  137       selects the number of seconds since then.
  138   %rY In calendars with years that don't coincide with the Gregorian
  139       years, this selects the calendar's year.
  140 .fi
  141 .PP
  142 .nf
  143   %dth  The day of the month as an ordinal number, 1st, 2nd, 3rd, etc.
  144   %mth  The month of the year as an ordinal number, 1st, 2nd, 3rd, etc.
  145 .fi
  146 .PP
  147 .nf
  148   %db The business day of the month (since last month's ultimo)
  149   %dB Number of business days until this month's ultimo
  150 .fi
  151 .PP
  152 Time specs:
  153 .nf
  154   %H  The hour of the day using a 24h clock, 2 digits (range 00 to 23)
  155   %I  The hour of the day using a 12h clock, 2 digits (range 01 to 12)
  156   %M  The minute (range 00 to 59)
  157   %N  The nanoseconds (range 000000000 to 999999999)
  158   %p  The string AM or PM, noon is PM and midnight is AM.
  159   %P  Like %p but in lowercase
  160   %S  The  (range 00 to 60, 60 is for leap seconds)
  161   %T  Equivalent to %H:%M:%S
  162 .fi
  163 .PP
  164 General specs:
  165 .nf
  166   %n  A newline character
  167   %t  A tab character
  168   %%  A literal % character
  169 .fi
  170 .PP
  171 Modifiers:
  172 .nf
  173   %O  Modifier to turn decimal numbers into Roman numerals
  174   %r  Modifier to turn units into real units
  175   %0  Modifier to turn on zero prefixes
  176   %SPC  Modifier to turn on space prefixes
  177   %-  Modifier to turn off prefixes altogether
  178   th  Suffix, read and print ordinal numbers
  179   b   Suffix, treat days as business days
  180 .fi
  181 .PP
  182 By design dates before 1601-01-01 are not supported.
  183 .PP
  184 For conformity here is a list of calendar designators and their
  185 corresponding format string:
  186 .nf
  187   ymd     %Y-%m-%d
  188   ymcw    %Y-%m-%c-%w
  189   ywd     %rY-W%V-%u
  190   bizda   %Y-%m-%db
  191   lilian     n/a
  192   ldn        n/a
  193   julian     n/a
  194   jdn        n/a
  195   matlab     n/a
  196   mdn        n/a
  197 .fi
  198 .PP
  199 These designators can be used as output format string, moreover,
  200 @code{lilian}/@code{ldn} and @code{julian}/@code{jdn} can also be used
  201 as input format string.
  202 
  203 .SH FORMAT SPECS FOR DURATIONS
  204 .PP
  205 Unlike time or absolute instants, durations are reference-free, i.e. the
  206 reference instant is not part of the duration.  As a result durations
  207 cannot be named, i.e. there is no naming scheme that applies to all
  208 durations and all references unambiguously.
  209 .PP
  210 Consequently, none of the format specifiers for date/times makes sense
  211 for durations in the literal sense.  However, to aid intuitive usage we
  212 reused format specifiers when they represent integral values and a valid
  213 unit for duration, as follows:
  214 .PP
  215 Date specs:
  216 .nf
  217   %c  Equivalent to %w
  218   %d  Duration in days
  219   %F  Equivalent to %dd with no resorting to bigger units
  220   %m  Duration in months
  221   %w  Duration in weeks
  222   %y  Equivalent to %Y
  223   %Y  Duration in years
  224 .fi
  225 .PP
  226 .nf
  227   %db Duration in business days
  228   %dB Equivalent to %db
  229 .fi
  230 .PP
  231 Time specs:
  232 .nf
  233   %H  Duration in hours
  234   %I  Equivalent to %H
  235   %M  Duration in minutes
  236   %S  Duration in seconds
  237   %T  Equivalent to %Ss without resorting to bigger units
  238 .fi
  239 .PP
  240 .nf
  241   %rS Duration in real-life seconds, as in including leap seconds
  242   %rT Equivalent to %rSs without resorting to bigger units
  243 .fi
  244 .PP
  245 General specs:
  246 .nf
  247   %n  A newline character
  248   %t  A tab character
  249   %%  A literal % character
  250 .fi
  251 .PP
  252 Modifiers:
  253 .nf
  254   %r    Modifier to turn units into real units
  255   %0    Modifier to pad refined values with zeroes
  256   %SPC  Modifier to pad refined values with spaces
  257   b     Suffix, treat days as business days
  258 .fi
  259 .PP
  260 .SH THE REFINEMENT RULE
  261 .PP
  262 Durations are somewhat ambiguous when it comes to representing them
  263 through format specifiers.  Unlike format specifiers in point-in-time
  264 representations duration specifiers can have an intra-line relationship.
  265 .PP
  266 So for instance a duration of 128 seconds might be presented through
  267 "%S" as "128" but similarly through "%M:%S" as
  268 "02:08" (read two minutes and 8 seconds).
  269 .PP
  270 There are several approaches to deal with this ambiguity.  The datediff
  271 tool will follow, what we call, the refinement rule.  That is,
  272 regardless of the position of a format specifier, if it is a valid
  273 /refinement/ of another specifier in the format string, then it
  274 will only show the fractional value, i.e. the value in its natural range
  275 with respect to the /refined/ specifier.
  276 .PP
  277 .nf
  278   %Y  possible refinements: %m, %w, %d
  279   %m  possible refinements: %w, %d
  280   %w  possible refinements: %d
  281   %d  possible refinements: %H, %M, %S
  282   %H  possible refinements: %M, %S
  283   %M  possible refinements: %S
  284 .fi
  285 .PP
  286 The refinement alternatives are listed in order of precedence and they
  287 are mutually exclusive.  I.e. it is not possible to express a duration
  288 in months and hours without having a "%d" specifier as well.  On
  289 the other hand in a chain of refinements inner elements are optional,
  290 i.e. you can express a duration in weeks and hours because every day has
  291 24 hours and hence there are 168 hours in a week.
  292 .PP
  293 In case of negative durations (the minuend is in the future relative to
  294 the subtrahend) only the largest unit will carry the minus sign.
  295 .PP
  296 Using the refinement rule keeps the format string dead simple, there's
  297 no need for operators or a full-blown language to distinguish the range
  298 ambiguity, which then would have to be escaped because they could also
  299 in theory be part of the literal characters of the format string,
  300 resulting more often than not in command lines that are hard to craft
  301 and even harder to understand later on (e.g. if used in shell scripts).
  302 .PP
  303 The refinement rule ingeniously covers the 99% case but, unlike other
  304 approaches, there's no way to display two unrefined values in the
  305 same format string, e.g. "'%w weeks (which is %d days)'".
  306 
  307 .SH EXAMPLES
  308 .PP
  309 .nf
  310   $ datediff 2012-03-02 2012-03-02
  311   0
  312   $
  313 .fi
  314 .PP
  315 .nf
  316   $ datediff 2012-03-02 2012-03-12
  317   10
  318   $
  319 .fi
  320 .PP
  321 .nf
  322   $ datediff 2012-03-02 2012-04-12
  323   41
  324   $
  325 .fi
  326 .PP
  327 .nf
  328   $ datediff 2012-03-12 2012-04-02
  329   21
  330   $
  331 .fi
  332 .PP
  333 .nf
  334   $ datediff 2012-04-02 2012-03-12
  335   -21
  336   $
  337 .fi
  338 .PP
  339 .nf
  340   $ datediff 2012-01-02 2012-02-29 -f '%dd'
  341   58d
  342   $
  343 .fi
  344 .PP
  345 .nf
  346   $ datediff 2012-01-02 2012-02-29 -f '%ww %dd'
  347   8w 2d
  348   $
  349 .fi
  350 .PP
  351 .nf
  352   $ datediff 10:00:00 10:00:00
  353   0s
  354   $
  355 .fi
  356 .PP
  357 .nf
  358   $ datediff 10:01:00 10:06:00
  359   300s
  360   $
  361 .fi
  362 .PP
  363 .nf
  364   $ datediff 10:06:00 10:01:00
  365   -300s
  366   $
  367 .fi
  368 .PP
  369 .nf
  370   $ datediff 10:01:00 11:03:10 -f '%S sec'
  371   3730 sec
  372   $
  373 .fi
  374 .PP
  375 .nf
  376   $ datediff 10:01:00 11:03:10 -f '%Mm %Ss'
  377   62m 10s
  378   $
  379 .fi
  380 .PP
  381 .nf
  382   $ datediff 10:01:00 11:03:10 -f '%H:%M:%S'
  383   1:2:10
  384   $
  385 .fi
  386 .PP
  387 .nf
  388   $ datediff 2012-03-02T10:04:00 2012-03-02T10:14:00
  389   600s
  390   $
  391 .fi
  392 .PP
  393 .nf
  394   $ datediff 2012-03-02T10:04:00 2012-03-02T10:14:00 -f '%M min'
  395   10 min
  396   $
  397 .fi
  398 .PP
  399 .nf
  400   $ datediff 2012-03-01T12:17:00 2012-03-02T14:00:00
  401   92580s
  402   $
  403 .fi
  404 .PP
  405 .nf
  406   $ datediff 2012-03-01T12:17:00 2012-03-02T14:00:00 -f '%d days and %S seconds'
  407   1 days and 6180 seconds
  408   $
  409 .fi
  410 .PP
  411 
  412 .SH AUTHOR
  413 Written by Sebastian Freundt <freundt@fresse.org>
  414 .PP
  415 .SH REPORTING BUGS
  416 Report bugs to: https://github.com/hroptatyr/dateutils/issues
  417 .PP
  418 
  419 
  420 
  421 .SH "SEE ALSO"
  422 The full documentation for
  423 .B datediff
  424 is maintained as a Texinfo manual.  If the
  425 .B info
  426 and
  427 .B datediff
  428 programs are properly installed at your site, the command
  429 .IP
  430 .B info (dateutils)datediff
  431 .PP
  432 should give you access to the complete manual.
  433 .\" yuck.m4man ends here