.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
.\" References consulted:
.\" Linux libc source code
.\" 2005-11-22 mtk, added Glibc Notes covering optional 'flag' and
.\" 'width' components of conversion specifications.
.\"
-.TH STRFTIME 3 2010-01-17 "GNU" "Linux Programmer's Manual"
+.TH STRFTIME 3 2014-03-18 "GNU" "Linux Programmer's Manual"
.SH NAME
strftime \- format date and time
.SH SYNOPSIS
.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
.IR "ordinary character sequences".
.PP
The characters of ordinary character sequences (including the null byte)
-are copied verbatim from \fIformat\fP to \fIs\fP. However, the characters
+are copied verbatim from
+.I format
+to
+.IR s .
+However, the characters
of conversion specifications are replaced as follows:
.TP
.B %a
-The abbreviated weekday name according to the current locale.
+The abbreviated name of the day of the week according to the current locale.
.TP
.B %A
-The full weekday name according to the current locale.
+The full name of the day of the week according to the current locale.
.TP
.B %b
The abbreviated month name according to the current locale.
.B %D
Equivalent to
.BR %m/%d/%y .
-(Yecch \(em for Americans only.
+(Yecch\(emfor Americans only.
Americans should note that in other countries
.B %d/%m/%y
is rather common.
(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.
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.
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
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
+.SH RETURN VALUE
+Provided that the result string,
+including the terminating null byte, does not exceed
+.I max
+bytes,
+.BR strftime ()
+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 ()
-function returns the number of characters 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 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
and
.B LC_TIME
are used.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
SVr4, C89, C99.
There are strict inclusions between the set of conversions
given in ANSI C (unmarked), those given in the Single UNIX Specification
included a double leap second
(there never has been such a minute).
.SH NOTES
-.SS ISO 8601 Week Dates
+.SS ISO 8601 week dates
.BR %G ,
.BR %g ,
and
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
+.SS Glibc notes
Glibc provides some extensions for conversion specifications.
(These extensions are not specified in POSIX.1-2001, but a few other
systems provide similar features.)
specifier character uses space-padding by default.
.TP
.B ^
-Convert alphabetic characters in result string to upper case.
+Convert alphabetic characters in result string to uppercase.
.TP
.B #
Swap the case of the result string.
-(This flag only works with certain conversion specifier characters,
+(This flag works only with certain conversion specifier characters,
and of these, it is only really useful with
.BR %Z .)
.PP
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
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 EXAMPLES
+.SH EXAMPLE
.BR "RFC\ 2822-compliant date format"
(with an English locale for %a and %b)
.PP
.PP
.in +2n
"%a,\ %d\ %b\ %y\ %T\ %z"
-.SS Example Program
+.SS Example program
The program below can be used to experiment with
.BR strftime ().
.PP
Result string is " 11"
.fi
.in
-.PP
-Here's the program source:
+.SS Program source
.nf
-
#include <time.h>
#include <stdio.h>
#include <stdlib.h>
exit(EXIT_SUCCESS);
}
.fi
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR date (1),
.BR time (2),
.BR ctime (3),
.BR setlocale (3),
.BR sprintf (3),
.BR strptime (3)
+.SH COLOPHON
+This page is part of release 3.65 of the Linux
+.I man-pages
+project.
+A description of the project,
+and information about reporting bugs,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
