(split) LDP: Update original to LDP v3.52.

[linuxjm/LDP_man-pages.git] / original / man3 / strftime.3

diff --git a/original/man3/strftime.3 b/original/man3/strftime.3
index fde487d..08b7945 100644 (file)
--- a/original/man3/strftime.3
+++ b/original/man3/strftime.3
@@ -34,7 +34,7 @@
 .\" 2005-11-22 mtk, added Glibc Notes covering optional 'flag' and
 .\"           'width' components of conversion specifications.
 .\"
-.TH STRFTIME 3  2012-05-10 "GNU" "Linux Programmer's Manual"
+.TH STRFTIME 3  2013-06-28 "GNU" "Linux Programmer's Manual"
 .SH NAME
 strftime \- format date and time
 .SH SYNOPSIS
@@ -47,9 +47,15 @@ strftime \- format date and time
 .SH DESCRIPTION
 The
 .BR strftime ()
-function formats the broken-down time \fItm\fP
-according to the format specification \fIformat\fP and places the
-result in the character array \fIs\fP of size \fImax\fP.
+function formats the broken-down time
+.I tm
+according to the format specification
+.I format
+and places the
+result in the character array
+.I s
+of size
+.IR max .
 .\" FIXME POSIX says: Local timezone information is used as though
 .\" strftime() called tzset().  But this doesn't appear to be the case
 .PP
@@ -63,7 +69,10 @@ All other character sequences are
 .IR "ordinary character sequences".
 .PP
 The characters of ordinary character sequences (including the null byte)
-are copied verbatim from \fIformat\fP to \fIs\fP.
+are copied verbatim from
+.I format
+to
+.IR s .
 However, the characters
 of conversion specifications are replaced as follows:
 .TP
@@ -184,7 +193,9 @@ In the POSIX locale this is equivalent to
 (SU)
 .TP
 .B %R
-The time in 24-hour notation (\fB%H:%M\fP). (SU)
+The time in 24-hour notation
+.RB ( %H:%M ).
+(SU)
 For a version including the seconds, see
 .B %T
 below.
@@ -200,7 +211,9 @@ The second as a decimal number (range 00 to 60).
 A tab character. (SU)
 .TP
 .B %T
-The time in 24-hour notation (\fB%H:%M:%S\fP). (SU)
+The time in 24-hour notation
+.RB ( %H:%M:%S ).
+(SU)
 .TP
 .B %u
 The day of the week as a decimal, range 1 to 7, Monday being 1.
@@ -256,7 +269,7 @@ or
 numeric timezone (that is, the hour and minute offset from UTC). (SU)
 .TP
 .B %Z
-The timezone or name or abbreviation.
+The timezone name or abbreviation.
 .TP
 .B %+
 .\" Nov 05 -- Not in Linux/glibc, but is in some BSDs (according to
@@ -305,24 +318,40 @@ modifier is to use
 alternative numeric symbols (say, roman numerals), and that of the
 E modifier is to use a locale-dependent alternative representation.
 .PP
-The broken-down time structure \fItm\fP is defined in \fI<time.h>\fP.
+The broken-down time structure
+.I tm
+is defined in
+.IR <time.h> .
 See also
 .BR ctime (3).
 .SH RETURN VALUE
-The
+Provided that the result string,
+including the terminating null byte, does not exceed
+.I max
+bytes,
 .BR strftime ()
-function returns the number of bytes placed
-in the array \fIs\fP, not including the terminating null byte,
-provided the string, including the terminating null byte, fits.
-Otherwise, it returns 0, and the contents of the array is undefined.
+returns the number of bytes (excluding the terminating null byte)
+placed in the array
+.IR s .
+If the length of the result string (including the terminating null byte)
+would exceed
+.I max
+bytes, then
+.BR strftime ()
+returns 0, and the contents of the array are undefined.
 (This behavior applies since at least libc 4.4.4;
 very old versions of libc, such as libc 4.4.1,
-would return \fImax\fP if the array was too small.)
+would return
+.I max
+if the array was too small.)
 .LP
-Note that the return value 0 does not necessarily indicate an error;
-for example, in many locales
+Note that the return value 0 does not necessarily indicate an error.
+For example, in many locales
 .B %p
 yields an empty string.
+An empty
+.I format
+string will likewise yield an empty string.
 .SH ENVIRONMENT
 The environment variables
 .B TZ
@@ -374,7 +403,10 @@ of the preceding year.
 For example, 1 January 2010 is a Friday,
 meaning that just three days of that calendar week fall in 2010.
 Thus, the ISO\ 8601 week-based system considers these days to be part of
-week 53 (\fB%V\fP) of the year 2009 (\fB%G\fP) ;
+week 53
+.RB ( %V )
+of the year 2009
+.RB ( %G );
 week 01 of ISO\ 8601 year 2010 starts on Monday, 4 January 2010.
 .SS Glibc notes
 Glibc provides some extensions for conversion specifications.
@@ -420,6 +452,24 @@ An optional decimal width specifier may follow the (possibly absent) flag.
 If the natural size of the field is smaller than this width,
 then the result string is padded (on the left) to the specified width.
 .SH BUGS
+If the output string would exceed
+.I max
+bytes,
+.I errno
+is
+.I not
+set.
+This makes it impossible to distinguish this error case from cases where the
+.I format
+string legitimately produces a zero-length output string.
+POSIX.1-2001
+does
+.I not
+specify any
+.I errno
+settings for
+.BR strftime ().
+
 Some buggy versions of
 .BR gcc (1)
 complain about the use of
@@ -448,7 +498,9 @@ my_strftime(char *s, size_t max, const char *fmt,
 
 Nowadays,
 .BR gcc (1)
-provides the \fI\-Wno\-format\-y2k\fP option to prevent the warning,
+provides the
+.IR \-Wno\-format\-y2k
+option to prevent the warning,
 so that the above workaround is no longer required.
 .SH EXAMPLE
 .BR "RFC\ 2822-compliant date format"