diff options
Diffstat (limited to 'manual/time.texi')
| -rw-r--r-- | manual/time.texi | 72 |
1 files changed, 71 insertions, 1 deletions
diff --git a/manual/time.texi b/manual/time.texi index 1022e1a41f..d711234c0b 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -536,6 +536,26 @@ Calling @code{localtime} has one other effect: it sets the variable Zone Functions}. @end deftypefun +Using the @code{localtime} function is a big problem in multi-threaded +programs. The result is returned in a static buffer and this is used in +all threads. POSIX.1c introduced a varient of this function. + +@comment time.h +@comment POSIX.1c +@deftypefun {struct tm *} localtime_r (const time_t *@var{time}, struct tm *@var{resultp}) +The @code{localtime_r} function works just like the @code{localtime} +function. It takes a pointer to a variable containing the calendar time +and converts it to the broken-down time format. + +But the result is not placed in a static buffer. Instead it is placed +in the object of type @code{struct tm} to which the parameter +@var{resultp} points. + +If the conversion is successful the function returns a pointer to the +object the result was written into, i.e., it returns @var{resultp}. +@end deftypefun + + @comment time.h @comment ISO @deftypefun {struct tm *} gmtime (const time_t *@var{time}) @@ -547,6 +567,21 @@ Recall that calendar times are @emph{always} expressed in coordinated universal time. @end deftypefun +As for the @code{localtime} function we have the problem that the result +is placed ina static variable. POSIX.1c also provides a replacement for +@code{gmtime}. + +@comment time.h +@comment POSIX.1c +@deftypefun {struct tm *} gmtime_r (const time_t *@var{time}, struct tm *@var{resultp}) +This function is similar to @code{localtime_r}, except that it converts +just like @code{gmtime} the given time as Coordinated Universal Time. + +If the conversion is successful the function returns a pointer to the +object the result was written into, i.e., it returns @var{resultp}. +@end deftypefun + + @comment time.h @comment ISO @deftypefun time_t mktime (struct tm *@var{brokentime}) @@ -602,6 +637,20 @@ string.) @end deftypefun @comment time.h +@comment POSIX.1c +@deftypefun {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer}) +This function is similar to @code{asctime} but instead of placing the +result in a static buffer it writes the string in the buffer pointed to +by the parameter @var{buffer}. This buffer should have at least room +for 16 bytes. + +If no error occurred the function returns a pointer to the string the +result was written into, i.e., it returns @var{buffer}. Otherwise +return @code{NULL}. +@end deftypefun + + +@comment time.h @comment ISO @deftypefun {char *} ctime (const time_t *@var{time}) The @code{ctime} function is similar to @code{asctime}, except that the @@ -617,6 +666,23 @@ does so. @xref{Time Zone Functions}. @end deftypefun @comment time.h +@comment POSIX.1c +@deftypefun {char *} ctime_r (const time_t *@var{time}, char *@var{buffer}) +This function is similar to @code{ctime}, only that it places the result +in the string pointed to by @var{buffer}. It is equivalent to (written +using gcc extensions, @xref{Statement Exprs,,,gcc,Porting and Using gcc}.): + +@smallexample +(@{ struct tm tm; asctime_r (localtime_r (time, &tm), buf); @}) +@end smallexample + +If no error occurred the function returns a pointer to the string the +result was written into, i.e., it returns @var{buffer}. Otherwise +return @code{NULL}. +@end deftypefun + + +@comment time.h @comment ISO @comment POSIX.2 @deftypefun size_t strftime (char *@var{s}, size_t @var{size}, const char *@var{template}, const struct tm *@var{brokentime}) @@ -885,7 +951,7 @@ A literal @samp{%} character. The @var{size} parameter can be used to specify the maximum number of characters to be stored in the array @var{s}, including the terminating null character. If the formatted time requires more than @var{size} -characters, @code{strftime} return zero and the content of the array +characters, @code{strftime} returns zero and the content of the array @var{s} is indetermined. Otherwise the return value indicates the number of characters placed in the array @var{s}, not including the terminating null character. @@ -1095,6 +1161,10 @@ GNU programs it is better to use the @code{tm_zone} member of the broken-down time structure, since @code{tm_zone} reports the correct abbreviation even when it is not the latest one. +Though the strings are declared as @code{char *} the user must stay away +from modifying these strings. Modying the strings will almost certainly +lead to trouble. + @end deftypevar @comment time.h |