X-Authentication-Warning: delorie.com: mail set sender to djgpp-workers-bounces using -f Date: Thu, 06 Jan 2005 16:45:35 -0700 From: Brian Inglis Subject: Re: *time_r patch In-reply-to: <01c4f43c$Blat.v2.2.2$620c39c0@zahav.net.il> To: djgpp-workers AT delorie DOT com Message-id: Organization: Systematic Software MIME-version: 1.0 X-Mailer: Forte Agent 1.93/32.576 English (American) Content-type: text/plain; charset=us-ascii References: <01c4f43c$Blat.v2.2.2$620c39c0 AT zahav DOT net DOT il> Content-Transfer-Encoding: 8bit X-MIME-Autoconverted: from quoted-printable to 8bit by delorie.com id j06Njv6U007669 Reply-To: djgpp-workers AT delorie DOT com Errors-To: nobody AT delorie DOT com X-Mailing-List: djgpp-workers AT delorie DOT com X-Unsubscribes-To: listserv AT delorie DOT com Precedence: bulk On Fri, 07 Jan 2005 00:08:22 +0200, Eli Zaretskii wrote: >> Date: Thu, 06 Jan 2005 00:16:24 -0700 >> From: Brian Inglis >> >> 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 + +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 + +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 + +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 + +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}