2007-06-22 James Youngman Better documentation for the fractional part of seconds fields for -printf and similar actions. * doc/find.texi (Time Components): Point out that the seconds field of the timestamp is often printed out with a fractional part of unspecified length and precision. The '%Tc' field has no seconds part. (Combined Time Formats): Point out the same thing for '%T@'. * find/find.1 (%A): Point out the same thing. * NEWS: Mention these changes. Index: NEWS =================================================================== RCS file: /sources/findutils/findutils/NEWS,v retrieving revision 1.184 diff -u -p -r1.184 NEWS --- NEWS 14 Jun 2007 09:37:24 -0000 1.184 +++ NEWS 22 Jun 2007 08:47:21 -0000 @@ -6,6 +6,12 @@ GNU findutils NEWS - User visible change #20139: find -[acm]time -N (wrongly) includes files from N days ago, as well as (correctly) from less than N days ago. +** Documentation Fixes + +Point out more explicitly that the subsecond timestamp support +introduced by findutils-4.3.3 introduces a change in the format of +several fields. + * Major changes in release 4.3.8 ** Bug Fixes Index: doc/find.texi =================================================================== RCS file: /sources/findutils/findutils/doc/find.texi,v retrieving revision 1.136 diff -u -p -r1.136 find.texi --- doc/find.texi 9 Jun 2007 12:56:07 -0000 1.136 +++ doc/find.texi 22 Jun 2007 08:47:25 -0000 @@ -1885,11 +1885,20 @@ time zone (e.g., EDT), or nothing if no @item M minute (00..59) @item S -second (00..61) +second (00..61). There is a fractional part. @item @@ -seconds since Jan. 1, 1970, 00:00 GMT. +seconds since Jan. 1, 1970, 00:00 GMT, with fractional part. @end table +The fractional part of the seconds field is of indeterminate length +and precision. That is, the length of the fractional part of the +seconds field will in general vary between findutils releases and +between systems. This means that it is unwise to assume that field +has any specific length. The length of this field is not usually a +guide to the precision of timestamps in the underlying file system. + + + @node Date Components @subsubsection Date Components @@ -1937,15 +1946,19 @@ time, 24-hour (hh:mm:ss) @item X locale's time representation (H:M:S) @item c -locale's date and time (Sat Nov 04 12:02:33 EST 1989) +locale's date and time in ctime format (Sat Nov 04 12:02:33 EST +1989). This format does nto include any fractional part in the +seconds field. @item D date (mm/dd/yy) @item x locale's date representation (mm/dd/yy) @item + -Date and time, separated by '+', for example `2004-04-28+22:22:05'. +Date and time, separated by '+', for example +`2004-04-28+22:22:05.0000000000'. The time is given in the current timezone (which may be affected by -setting the TZ environment variable). This is a GNU extension. +setting the TZ environment variable). This is a GNU extension. The +seconds field includes a fractional part. @end table @node Formatting Flags Index: find/find.1 =================================================================== RCS file: /sources/findutils/findutils/find/find.1,v retrieving revision 1.81 diff -u -p -r1.81 find.1 --- find/find.1 12 Jun 2007 19:34:31 -0000 1.81 +++ find/find.1 22 Jun 2007 08:47:26 -0000 @@ -807,7 +807,7 @@ available on all systems, due to differe systems. .RS .IP @ -seconds since Jan. 1, 1970, 00:00 GMT. +seconds since Jan. 1, 1970, 00:00 GMT, with fractional part. .PP Time fields: .IP H @@ -825,13 +825,14 @@ locale's AM or PM .IP r time, 12-hour (hh:mm:ss [AP]M) .IP S -second (00..61) +Second (00.00 .. 61.00). There is a fractional part. .IP T time, 24-hour (hh:mm:ss) .IP + -Date and time, separated by '+', for example `2004\-04\-28+22:22:05'. -The time is given in the current timezone (which may be affected by -setting the TZ environment variable). This is a GNU extension. +Date and time, separated by '+', for example +`2004\-04\-28+22:22:05.0'. This is a GNU extension. The time is +given in the current timezone (which may be affected by setting the TZ +environment variable). The seconds field includes a fractional part. .IP X locale's time representation (H:M:S) .IP Z @@ -847,7 +848,11 @@ locale's abbreviated month name (Jan..De .IP B locale's full month name, variable length (January..December) .IP c -locale's date and time (Sat Nov 04 12:02:33 EST 1989) +locale's date and time (Sat Nov 04 12:02:33 EST 1989). The format is +the same as for +.BR ctime (3) +and so to preserve compatibility with that format, there is no fractional part +in the seconds field. .IP d day of month (01..31) .IP D