Mail Archives: djgpp-workers/2005/01/06/18:46:04
On Fri, 07 Jan 2005 00:08:22 +0200, Eli Zaretskii <eliz AT gnu DOT org> wrote:
>> Date: Thu, 06 Jan 2005 00:16:24 -0700
>> From: Brian Inglis <Brian DOT Inglis AT SystematicSw DOT ab DOT ca>
>>
>> Here's a patch to src/libc/ansi/ctime.c, src/libc/ansi/ctime.txh,
>> and include/libc/stubs.h to add POSIX thread safe functions
>> asctime_r(), ctime_r(), gmtime_r(), and localtime_r().
>
>Thanks.
>
>> +++ src/libc/ansi/time/ctime.txh 6 Jan 2005 07:00:19 -0000
>> @@ -13,6 +13,7 @@ char *ctime(const time_t *cal);
>> This function returns an ASCII representation of the time in @var{cal}.
>> This is equivalent to @code{asctime(localtime(cal))}. @xref{asctime}.
>> @xref{localtime}.
>> +@xref{ctime_r}.
>
>Why did you add this 3rd cross-reference? The other two are there
>because ctime is explained in terms of calling those two functions;
>by contrast, ctime_r is not mentioned anywhere in the text.
>
>If you wanted a ``see-also'' type of reference, that is okay, but
>please add some text that would explain why you think it is useful for
>the reader to look there. In other words, give the readers enough
>information to decide whether they want to read about the referenced
>function.
Please see revised patch below.
>> +This is equivalent to @code{asctime_r(localtime_r(cal,&tm), buf)},
>> +where @var{tm} is automatically/dynamically allocated.
>
>This text is confusing wrt the "&tm" part. I suggest to reword like
>this:
>
> This is equivalent to @code{asctime_r(localtime_r(cal,&tm), buf)},
> where @var{tm} is a variable of the type @code{struct tm}.
Modified as suggested.
>> +@xref{asctime_r}.
>> +@xref{localtime_r}.
>> +@xref{ctime}.
>
>See above about the 3rd xref.
Please see revised patch below.
>> +This function returns an ASCII representation,
>> +as generated by @ref{asctime},
>> +of the broken down calendar time from @var{tptr},
>
>I'd advise against such ``clever'' uses of @ref (they look awkard in
>Info and simply wrong in the printed copy of the manual). Instead,
>say something like
>
> This function returns an ASCII representation of the broken down
> calendar time from @var{tptr}, which is identical to the one
> generated by @code{asctime} (@pxref{asctime}),
Reworded in a few places for consistency.
>> +See @ref{gmtime}, for the description of @code{struct tm}.
>
>"See @ref" is exactly equivalent to "@xref", so please use the latter
>here. (Yes, I know that "See @ref" is used elsewhere in the manual;
>feel free to fix those other places as well, if you have time and
>energy.)
Used including elsewhere.
>Thanks again for working on this.
De nada!
Also removed some redundant definitions of struct tm
and changed them to refer to @xref{gmtime}.
ISTM that mktime would be a better and unique xref. Thoughts?
Thanks. Take care, Brian Inglis
Index: src/libc/ansi/time/ctime.txh
===================================================================
RCS file: /cvs/djgpp/djgpp/src/libc/ansi/time/ctime.txh,v
retrieving revision 1.10
diff -u -t -r1.10 ctime.txh
--- src/libc/ansi/time/ctime.txh 5 Mar 2003 19:42:31 -0000 1.10
+++ src/libc/ansi/time/ctime.txh 6 Jan 2005 23:36:51 -0000
@@ -10,19 +10,67 @@
@subheading Description
-This function returns an ASCII representation of the time in @var{cal}.
-This is equivalent to @code{asctime(localtime(cal))}. @xref{asctime}.
+This function returns a string representing the time from @var{cal}.
+The string returned is always 26 characters and has this format:
+
+@example
+Sun Jan 01 12:34:56 1993\n\0
+@end example
+
+This function is equivalent to @code{asctime(localtime(cal))}.
+@xref{asctime}.
@xref{localtime}.
+The string pointed to is in a static buffer and will be overwritten with
+each call to ctime.
+The string should be copied if it needs to be preserved.
+@xref{ctime_r} for an alternate interface that allows the caller
+to provide a buffer to receive the string.
@subheading Return Value
-The ascii representation of the time.
+A pointer to a static buffer containing the string representing the time.
@subheading Portability
@portability ansi, posix
@c ----------------------------------------------------------------------
+@node ctime_r, time
+@findex ctime_r
+@subheading Syntax
+
+@example
+#include <time.h>
+
+char *ctime_r(const time_t *cal, char *buf);
+@end example
+
+@subheading Description
+
+This function returns a string representing the time from @var{cal}.
+The string returned is always 26 characters and has this format:
+
+@example
+Sun Jan 01 12:34:56 1993\n\0
+@end example
+
+This function is equivalent to @code{asctime_r(localtime_r(cal,&tm), buf)}
+where @var{tm} is a variable of type @code{struct tm}.
+@xref{asctime_r}.
+@xref{localtime_r}.
+The buffer @var{buf} passed must be at least 26 bytes long.
+
+@xref{ctime} for an alternate ISO Standard interface.
+
+@subheading Return Value
+
+A pointer to @var{buf} containing the string representing the time.
+
+@subheading Portability
+
+@portability !ansi, posix
+
+@c ----------------------------------------------------------------------
@node asctime, time
@findex asctime
@subheading Syntax
@@ -35,7 +83,7 @@
@subheading Description
-This function returns an ASCII representation of the time represented by
+This function returns a string representing the time from
@var{tptr}. The string returned is always 26 characters and has this
format:
@@ -44,41 +92,71 @@
@end example
The string pointed to is in a static buffer and will be overwritten with
-each call to asctime. The data should be copied if it needs to be
+each call to asctime. The string should be copied if it needs to be
preserved.
+@xref{asctime_r} for an alternate interface that allows the caller
+to provide a buffer to receive the string.
+
+@xref{gmtime} for a description of type @code{struct tm}.
+
+@subheading Return Value
-The layout of the @code{struct tm} structure is like this:
+A pointer to a static buffer containing the string representing the time.
+
+@subheading Portability
+
+@portability ansi, posix
+
+@subheading Example
@example
-struct tm @{
- int tm_sec; /* seconds after the minute [0-60] */
- int tm_min; /* minutes after the hour [0-59] */
- int tm_hour; /* hours since midnight [0-23] */
- int tm_mday; /* day of the month [1-31] */
- int tm_mon; /* months since January [0-11] */
- int tm_year; /* years since 1900 */
- int tm_wday; /* days since Sunday [0-6] */
- int tm_yday; /* days since January 1 [0-365] */
- int tm_isdst; /* Daylight Savings Time flag */
- long tm_gmtoff; /* offset from GMT in seconds */
- char * tm_zone; /* timezone abbreviation */
-@};
+time_t now;
+time(&now);
+printf("The current time is %s", asctime(localtime(&now)));
+@end example
+
+@c ----------------------------------------------------------------------
+@node asctime_r, time
+@findex asctime_r
+@subheading Syntax
+
+@example
+#include <time.h>
+
+char *asctime_r(const struct tm * restrict tptr, char * restrict buf);
@end example
+@subheading Description
+
+This function returns a string representing the time from @var{tptr}.
+The string returned is always 26 characters and has this
+format:
+
+@example
+Sun Jan 01 12:34:56 1993\n\0
+@end example
+
+@xref{asctime} for an alternate ISO Standard interface.
+
+@xref{gmtime} for a description of type @code{struct tm}.
+
@subheading Return Value
-A pointer to the string.
+A pointer to @var{buf} containing the character representation of the time.
@subheading Portability
-@portability ansi, posix
+@portability !ansi, posix
@subheading Example
@example
time_t now;
+struct tm tm;
+char buf[26];
+
time(&now);
-printf("The current time is %s", asctime(localtime(&now)));
+printf("The current time is %s", asctime_r(localtime_r(&now,&tm),buf));
@end example
@c ----------------------------------------------------------------------
@@ -95,7 +173,7 @@
@subheading Description
-Converts the time represented by @var{tod} into a structure.
+Converts the time represented by @var{tod} into a structure.
The return structure has this format:
@@ -115,6 +193,15 @@
@};
@end example
+The structure pointed to is static and will be overwritten with
+each call to gmtime.
+The structure should be copied if it needs to be preserved.
+@xref{gmtime_r} for an alternate interface that allows the caller
+to provide the structure to be filled.
+
+@xref{localtime} for a similar function that returns the information
+corrected for the local time zone instead of GMT.
+
@subheading Return Value
A pointer to a static structure which is overwritten with each call.
@@ -133,6 +220,47 @@
@end example
@c ----------------------------------------------------------------------
+@node gmtime_r, time
+@findex gmtime_r
+@subheading Syntax
+
+@example
+#include <time.h>
+
+struct tm *gmtime_r(const time_t * restrict tod, struct tm * restrict tptr);
+@end example
+
+@subheading Description
+
+Converts the time represented by @var{tod} into
+a broken down calendar time structure @var{tptr}.
+
+@xref{gmtime} for a description of type @code{struct tm}.
+
+@xref{gmtime} for an alternate ISO Standard interface.
+
+@xref{localtime_r} for a similar function that returns the information
+corrected for the local time zone instead of GMT.
+
+@subheading Return Value
+
+A pointer to @var{tptr} containing the broken down calendar time.
+
+@subheading Portability
+
+@portability !ansi, posix
+
+@subheading Example
+
+@example
+time_t x;
+struct tm *t;
+struct tm tm;
+time(&x);
+t = gmtime_r(&x, &tm);
+@end example
+
+@c ----------------------------------------------------------------------
@node localtime, time
@findex localtime
@subheading Syntax
@@ -146,9 +274,15 @@
@subheading Description
Converts the time represented by @var{tod} into a structure, correcting
-for the local timezone. See @ref{gmtime}, for the description of
+for the local timezone. @xref{gmtime}, for the description of
@code{struct tm}.
+The structure pointed to is static and will be overwritten with
+each call to localtime.
+The structure should be copied if it needs to be preserved.
+@xref{localtime_r} for an alternate interface that allows the caller
+to provide the structure to be filled.
+
@subheading Return Value
A pointer to a static structure which is overwritten with each call.
@@ -158,6 +292,34 @@
@portability ansi, posix
@c ----------------------------------------------------------------------
+@node localtime_r, time
+@findex localtime_r
+@subheading Syntax
+
+@example
+#include <time.h>
+
+struct tm *localtime_r(const time_t * restrict tod, struct tm * restrict tptr);
+@end example
+
+@subheading Description
+
+Converts the time represented by @var{tod} into structure @var{tptr},
+correcting for the local timezone.
+
+@xref{gmtime}, for the description of @code{struct tm}.
+
+@xref{localtime} for an alternate ISO Standard interface.
+
+@subheading Return Value
+
+A pointer to @var{tptr} containing the broken down calendar time.
+
+@subheading Portability
+
+@portability !ansi, posix
+
+@c ----------------------------------------------------------------------
@node mktime, time
@findex mktime
@vindex TZ AT r{ environment variable, and time since 1970}
- Raw text -