X-Authentication-Warning: delorie.com: mail set sender to djgpp-workers-bounces using -f Date: Fri, 07 Jan 2005 09:58:15 -0700 From: Brian Inglis Subject: Re: *time_r patch In-reply-to: <01c4f4bb$Blat.v2.2.2$12c86080@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> <01c4f4bb$Blat.v2.2.2$12c86080 AT zahav DOT net DOT il> Content-Transfer-Encoding: 8bit X-MIME-Autoconverted: from quoted-printable to 8bit by delorie.com id j07GwNKw006365 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 15:15:14 +0200, Eli Zaretskii wrote: >> Date: Thu, 06 Jan 2005 16:45:35 -0700 >> From: Brian Inglis >> >> Please see revised patch below. > >Thanks. > >I have a few minor comments: > >> +@xref{ctime_r} for an alternate interface that allows the caller >> +to provide a buffer to receive the string. > >You need to put some punctuation, usually a comma or a period, after >"@xref{ctime_r}" (makeinfo should have complained about that). (There >are more xref's that lack such a punctuation, please fix them all.) > >Also, I think "to store the string" is better than "to receive the >string", because the previous text says that the string is stored in a >static buffer. > >> +to provide a buffer to receive the string. > >Same here. > >> +The structure pointed to is static and will be overwritten with >> +each call to gmtime. > >"gmtime" is a C identifier, so it needs to be in @code{}. (There are >a few other sentences like this one where the function name is not in >@code{}.) Fixed and appended. Appreciate all the comments. 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 7 Jan 2005 16:55:08 -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 @code{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 store 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 @code{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 store 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 @code{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 @code{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}