diff options
author | Paul Eggert <eggert@cs.ucla.edu> | 2005-02-24 00:27:44 +0000 |
---|---|---|
committer | Paul Eggert <eggert@cs.ucla.edu> | 2005-02-24 00:27:44 +0000 |
commit | b2265ebeea46ea3ead0f9967b4c9a74ab097e47a (patch) | |
tree | 01a74856eb0e8d1c8f87a56ca18864f26e2bd432 /doc/coreutils.texi | |
parent | 157fdac5711801f617b98c0b9b56aefae901922c (diff) | |
download | coreutils-b2265ebeea46ea3ead0f9967b4c9a74ab097e47a.tar.xz |
(Time directives): Say that %k, %l, and %P are
GNU extensions.
For %p and %P, mention handling of noon and midnight.
For %s, use ISO 8601, and mention handling of leap seconds.
For %S, clarify mention of leap seconds.
For %T, say that it's the same as %H:%M:%S.
For %X, don't say that it must be the same as %H:%M:%S.
For %z and %Z, clarify which time zones are used. These options
are now affected by --date, so don't claim that they're not.
(Date directives): %C is now all but the last two chars of %Y.
For %D, say that it's equivalent to %m/%d/%y.
For %e, use blank in example.
For %h, use @code for %b.
For %Y, mention what happens with outlandish years.
(Padding and other flags): Renamed from Padding.
Mention that the flags are GNU extensions.
Mention the 0 and ^ flags.
Mention field widths an modifiers.
(Examples of date): - is a flag, not a modifier.
Diffstat (limited to 'doc/coreutils.texi')
-rw-r--r-- | doc/coreutils.texi | 115 |
1 files changed, 78 insertions, 37 deletions
diff --git a/doc/coreutils.texi b/doc/coreutils.texi index f1483fcfd..f235fb2a0 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -398,7 +398,7 @@ System context * Time directives:: Time directives * Date directives:: Date directives * Literal directives:: Literal directives -* Padding:: Padding +* Padding and other flags:: Padding and other flags * Setting the time:: Setting the time * Options for date:: Options for @command{date} * Examples of date:: Examples of @command{date} @@ -11441,7 +11441,7 @@ are printed unchanged. The directives are described below. * Time directives:: %[HIklMprsSTXzZ] * Date directives:: %[aAbBcCdDhjmUwWxyY] * Literal directives:: %[%nt] -* Padding:: Pad with zeroes, spaces (%_), or nothing (%-). +* Padding and other flags:: Pad with zeroes, spaces (%_), etc. * Setting the time:: Changing the system clock. * Options for date:: Instead of the current time. * Examples of date:: Examples. @@ -11461,44 +11461,51 @@ hour (00@dots{}23) @item %I hour (01@dots{}12) @item %k -hour ( 0@dots{}23) +hour ( 0@dots{}23). +This is a @acronym{GNU} extension. @item %l -hour ( 1@dots{}12) +hour ( 1@dots{}12). +This is a @acronym{GNU} extension. @item %M minute (00@dots{}59) @item %N nanoseconds (000000000@dots{}999999999) @item %p -locale's upper case @samp{AM} or @samp{PM} (blank in many locales) +locale's upper case @samp{AM} or @samp{PM} (blank in many locales). +Noon is treated as @samp{PM} and midnight as @samp{AM}. @item %P -locale's lower case @samp{am} or @samp{pm} (blank in many locales) +locale's lower case @samp{am} or @samp{pm} (blank in many locales). +Noon is treated as @samp{pm} and midnight as @samp{am}. +This is a @acronym{GNU} extension. @item %r -time, 12-hour (hh:mm:ss [AP]M) +locale's 12-hour time (hh:mm:ss [AP]M) @item %R -time, 24-hour (hh:mm). Same as @code{%H:%M}. +24-hour hour and minute. Same as @code{%H:%M}. @item %s @cindex epoch, seconds since @cindex seconds since the epoch @cindex beginning of time -seconds since the epoch, i.e., 1 January 1970 00:00:00 UTC (a GNU extension). -For examples, @xref{%s-examples}. +seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. +Leap seconds are not counted unless leap second support is available. +This is a @acronym{GNU} extension. +@xref{%s-examples}, for examples. @item %S -second (00@dots{}60). The range is [00@dots{}60], and not [00@dots{}59], -in order to accommodate the occasional positive leap second. +second (00@dots{}60). This may be @samp{60} if leap seconds are supported. @item %T -time, 24-hour (hh:mm:ss) +24-hour hour, minute, and second. Same as @code{%H:%M:%S}. @item %X -locale's time representation (%H:%M:%S) +locale's time representation (hh:mm:ss) @item %z -RFC-2822 style numeric time zone (e.g., @samp{-0600} or @samp{+0100}), -or nothing if no -time zone is determinable. This value reflects the @emph{current} time -zone. It isn't changed by the @option{--date} option. +@w{RFC 2822}/@w{ISO 8601} style numeric time zone (e.g., @samp{-0600} +or @samp{+0100}), or nothing if no +time zone is determinable. This value reflects the numeric time zone +appropriate for the current time, using the time zone rules specified +by the @env{TZ} environment variable. +The time (and optionally, the time zone rules) can be overridden +by the @option{--date} option. @item %Z -time zone (e.g., EDT), or nothing if no time zone is -determinable. -Note that this value reflects the @emph{current} time zone. -It isn't changed by the @option{--date} option. +alphabetic time zone abbreviation (e.g., @samp{EDT}), or nothing if no +time zone is determinable. See @samp{%z} for how it is determined. @end table @@ -11522,13 +11529,16 @@ locale's full month name, variable length (January@dots{}December) @item %c locale's date and time (Sat Nov 04 12:02:33 EST 1989) @item %C -century (year divided by 100 and truncated to an integer) (00@dots{}99) +century. This is like @code{%Y}, except the last two digits are omitted. +For example, it is @samp{20} if @code{%Y} is @samp{2000}, +and is @samp{-0} if @code{%Y} is @samp{-001}. +It is normally at least two characters, but it may be more. @item %d day of month (01@dots{}31) @item %D -date (mm/dd/yy) +date (equivalent to @code{%m/%d/%y}) @item %e -blank-padded day of month (1@dots{}31) +blank-padded day of month ( 1@dots{}31) @item %F the @w{ISO 8601} standard date format: @code{%Y-%m-%d}. This is the preferred form for all uses. @@ -11543,7 +11553,7 @@ and value as @code{%Y}, except that if the ISO week number (see @code{%V}) belongs to the previous or next year, that year is used instead. @item %h -same as %b +same as @code{%b} @item %j day of year (001@dots{}366) @item %m @@ -11569,7 +11579,8 @@ locale's date representation (mm/dd/yy) @item %y last two digits of year (00@dots{}99) @item %Y -year (1970@dots{}.) +year. This is normally at least four characters, but it may be more. +Year 0000 precedes year 0001, and year -001 precedes year 0000. @end table @@ -11591,8 +11602,8 @@ a horizontal tab @end table -@node Padding -@subsection Padding +@node Padding and other flags +@subsection Padding and other flags @cindex numeric field padding @cindex padding of numeric fields @@ -11600,9 +11611,11 @@ a horizontal tab By default, @command{date} pads numeric fields with zeroes, so that, for example, numeric months are always output as two digits. -@acronym{GNU} @command{date} -recognizes the following numeric modifiers between the @samp{%} and the -directive. +Numbers that do not have a range are never +padded, since there is no natural width for them. + +As a @acronym{GNU} extension, @command{date} recognizes any of the +following optional flags after the @samp{%}: @table @samp @item - @@ -11611,12 +11624,14 @@ human consumption. @item _ (underscore) pad the field with spaces; useful if you need a fixed number of characters in the output, but zeroes are too distracting. +@item 0 +(zero) Pad with zeros even if the format specifies padding with spaces. +@item ^ +Use upper case characters if possible. @end table @noindent -These are GNU extensions. - -Here is an example illustrating the differences: +Here are some examples of padding: @example date +%d/%m -d "Feb 1" @@ -11627,6 +11642,31 @@ date +%_d/%_m -d "Feb 1" @result{} 1/ 2 @end example +As a @acronym{GNU} extension, you can specify the field width +after any flag, as a decimal number. If the natural size of the +output is of the field has less than the specified number of characters, +the result is written right adjusted and space padded to the given +size. + +An optional modifier can follow the optional flag and width +specification. The modifiers are: + +@table @code +@item E +Use the locale's alternate representation for date and time. This +modifier applies to the @code{%c}, @code{%C}, @code{%x}, @code{%X}, +@code{%y} and @code{%Y} format specifiers. In a Japanese locale, for +example, @code{%Ex} might yield a date format based on the Japanese +Emperors' reigns. + +@item O +Use the locale's alternate numeric symbols for numbers. This modifier +applies only to numeric format specifiers. +@end table + +If the format supports the modifier but no alternate representation +is available, it is ignored. + @node Setting the time @subsection Setting the time @@ -11837,7 +11877,8 @@ for example @samp{date -d 1may '+%B %d'} will print @samp{May 01}. @item To print a date without the leading zero for one-digit days -of the month, you can use the (GNU extension) @code{-} modifier to suppress +of the month, you can use the (@acronym{GNU} extension) +@code{-} flag to suppress the padding altogether: @example @@ -11846,7 +11887,7 @@ date -d 1may '+%B %-d @item To print the current date and time in the format required by many -non-GNU versions of @command{date} when setting the system clock: +non-@acronym{GNU} versions of @command{date} when setting the system clock: @example date +%m%d%H%M%Y.%S |