mirror of https://github.com/mkerrisk/man-pages
472 lines
12 KiB
Groff
472 lines
12 KiB
Groff
.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\" References consulted:
|
|
.\" Linux libc source code
|
|
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
|
|
.\" 386BSD man pages
|
|
.\" GNU texinfo documentation on glibc date/time functions.
|
|
.\" Modified Sat Jul 24 18:03:44 1993 by Rik Faith (faith@cs.unc.edu)
|
|
.\" Applied fix by Wolfgang Franke, aeb, 961011
|
|
.\" Corrected return value, aeb, 970307
|
|
.\" Added Single Unix Spec conversions and %z, aeb/esr, 990329.
|
|
.\" 2005-11-22 mtk, added Glibc Notes covering optional 'flag' and
|
|
.\" 'width' components of conversion specifications.
|
|
.\"
|
|
.TH STRFTIME 3 2005-11-23 "GNU" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
strftime \- format date and time
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <time.h>
|
|
.sp
|
|
.BI "size_t strftime(char *" s ", size_t " max ", const char *" format ,
|
|
.BI " const struct tm *" tm );
|
|
.fi
|
|
.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.
|
|
.PP
|
|
Ordinary characters placed in the format string are copied to \fIs\fP
|
|
without conversion.
|
|
.I "Conversion specifications"
|
|
are introduced by a \(aq%\(aq
|
|
character, and terminated by a
|
|
.IR "conversion specifier character" ,
|
|
and are replaced in \fIs\fP as follows:
|
|
.TP
|
|
.B %a
|
|
The abbreviated weekday name according to the current locale.
|
|
.TP
|
|
.B %A
|
|
The full weekday name according to the current locale.
|
|
.TP
|
|
.B %b
|
|
The abbreviated month name according to the current locale.
|
|
.TP
|
|
.B %B
|
|
The full month name according to the current locale.
|
|
.TP
|
|
.B %c
|
|
The preferred date and time representation for the current locale.
|
|
.TP
|
|
.B %C
|
|
The century number (year/100) as a 2-digit integer. (SU)
|
|
.TP
|
|
.B %d
|
|
The day of the month as a decimal number (range 01 to 31).
|
|
.TP
|
|
.B %D
|
|
Equivalent to
|
|
.BR %m/%d/%y .
|
|
(Yecch \(em for Americans only.
|
|
Americans should note that in other countries
|
|
.B %d/%m/%y
|
|
is rather common.
|
|
This means that in international context this format is
|
|
ambiguous and should not be used.) (SU)
|
|
.TP
|
|
.B %e
|
|
Like
|
|
.BR %d ,
|
|
the day of the month as a decimal number, but a leading
|
|
zero is replaced by a space. (SU)
|
|
.TP
|
|
.B %E
|
|
Modifier: use alternative format, see below. (SU)
|
|
.TP
|
|
.B %F
|
|
Equivalent to
|
|
.B %Y-%m-%d
|
|
(the ISO 8601 date format). (C99)
|
|
.TP
|
|
.B %G
|
|
The ISO 8601 year with century as a decimal number.
|
|
The 4-digit year corresponding to the ISO week number (see
|
|
.BR %V ).
|
|
This has the same format and value as
|
|
.BR %y ,
|
|
except that if the
|
|
ISO week number belongs to the previous or next year,
|
|
that year is used instead. (TZ)
|
|
.TP
|
|
.B %g
|
|
Like
|
|
.BR %G ,
|
|
but without century, that is, with a 2-digit year (00-99). (TZ)
|
|
.TP
|
|
.B %h
|
|
Equivalent to
|
|
.BR %b .
|
|
(SU)
|
|
.TP
|
|
.B %H
|
|
The hour as a decimal number using a 24-hour clock (range 00 to 23).
|
|
.TP
|
|
.B %I
|
|
The hour as a decimal number using a 12-hour clock (range 01 to 12).
|
|
.TP
|
|
.B %j
|
|
The day of the year as a decimal number (range 001 to 366).
|
|
.TP
|
|
.B %k
|
|
The hour (24-hour clock) as a decimal number (range 0 to 23);
|
|
single digits are preceded by a blank. (See also
|
|
.BR %H .)
|
|
(TZ)
|
|
.TP
|
|
.B %l
|
|
The hour (12-hour clock) as a decimal number (range 1 to 12);
|
|
single digits are preceded by a blank. (See also
|
|
.BR %I .)
|
|
(TZ)
|
|
.TP
|
|
.B %m
|
|
The month as a decimal number (range 01 to 12).
|
|
.TP
|
|
.B %M
|
|
The minute as a decimal number (range 00 to 59).
|
|
.TP
|
|
.B %n
|
|
A newline character. (SU)
|
|
.TP
|
|
.B %O
|
|
Modifier: use alternative format, see below. (SU)
|
|
.TP
|
|
.B %p
|
|
Either "AM" or "PM" according to the given time value, or the
|
|
corresponding strings for the current locale.
|
|
Noon is treated as "pm" and midnight as "am".
|
|
.TP
|
|
.B %P
|
|
Like
|
|
.B %p
|
|
but in lowercase: "am" or "pm" or a corresponding
|
|
string for the current locale. (GNU)
|
|
.TP
|
|
.B %r
|
|
The time in a.m. or p.m. notation.
|
|
In the POSIX locale this is equivalent to
|
|
.BR "%I:%M:%S %p" .
|
|
(SU)
|
|
.TP
|
|
.B %R
|
|
The time in 24-hour notation (\fB%H:%M\fP). (SU)
|
|
For a version including the seconds, see
|
|
.B %T
|
|
below.
|
|
.TP
|
|
.B %s
|
|
The number of seconds since the Epoch, that is, since 1970-01-01
|
|
00:00:00 UTC. (TZ)
|
|
.TP
|
|
.B %S
|
|
The second as a decimal number (range 00 to 60).
|
|
(The range is up to 60 to allow for occasional leap seconds.)
|
|
.TP
|
|
.B %t
|
|
A tab character. (SU)
|
|
.TP
|
|
.B %T
|
|
The time in 24-hour notation (\fB%H:%M:%S\fP). (SU)
|
|
.TP
|
|
.B %u
|
|
The day of the week as a decimal, range 1 to 7, Monday being 1.
|
|
See also
|
|
.BR %w .
|
|
(SU)
|
|
.TP
|
|
.B %U
|
|
The week number of the current year as a decimal number,
|
|
range 00 to 53, starting with the first Sunday as the first day
|
|
of week 01.
|
|
See also
|
|
.B %V
|
|
and
|
|
.BR %W .
|
|
.TP
|
|
.B %V
|
|
The ISO 8601:1988 week number of the current year as a decimal number,
|
|
range 01 to 53, where week 1 is the first week that has at least
|
|
4 days in the current year, and with Monday as the first day of
|
|
the week.
|
|
See also
|
|
.B %U
|
|
and
|
|
.BR %W .
|
|
(SU)
|
|
.TP
|
|
.B %w
|
|
The day of the week as a decimal, range 0 to 6, Sunday being 0.
|
|
See also
|
|
.BR %u .
|
|
.TP
|
|
.B %W
|
|
The week number of the current year as a decimal number,
|
|
range 00 to 53, starting with the first Monday as the first day of week 01.
|
|
.TP
|
|
.B %x
|
|
The preferred date representation for the current locale without the time.
|
|
.TP
|
|
.B %X
|
|
The preferred time representation for the current locale without the date.
|
|
.TP
|
|
.B %y
|
|
The year as a decimal number without a century (range 00 to 99).
|
|
.TP
|
|
.B %Y
|
|
The year as a decimal number including the century.
|
|
.TP
|
|
.B %z
|
|
The time-zone as hour offset from GMT.
|
|
Required to emit RFC\ 822-conformant dates
|
|
(using "%a,\ %d\ %b\ %Y\ %H:%M:%S\ %z"). (GNU)
|
|
.TP
|
|
.B %Z
|
|
The time zone or name or abbreviation.
|
|
.TP
|
|
.B %+
|
|
.\" Nov 05 -- Not in Linux/glibc, but is in some BSDs (according to
|
|
.\" their man pages)
|
|
The date and time in
|
|
.BR date (1)
|
|
format. (TZ)
|
|
(Not supported in glibc2.)
|
|
.TP
|
|
.B %%
|
|
A literal \(aq%\(aq character.
|
|
.PP
|
|
Some conversion specifications can be modified by preceding the
|
|
conversion specifier character by the
|
|
.B E
|
|
or
|
|
.B O
|
|
.I modifier
|
|
to indicate that an alternative format should be used.
|
|
If the alternative format or specification does not exist for
|
|
the current locale, the behavior will be as if the unmodified
|
|
conversion specification were used. (SU)
|
|
The Single Unix Specification mentions
|
|
.BR %Ec ,
|
|
.BR %EC ,
|
|
.BR %Ex ,
|
|
.BR %EX ,
|
|
.BR %Ey ,
|
|
.BR %EY ,
|
|
.BR %Od ,
|
|
.BR %Oe ,
|
|
.BR %OH ,
|
|
.BR %OI ,
|
|
.BR %Om ,
|
|
.BR %OM ,
|
|
.BR %OS ,
|
|
.BR %Ou ,
|
|
.BR %OU ,
|
|
.BR %OV ,
|
|
.BR %Ow ,
|
|
.BR %OW ,
|
|
.BR %Oy ,
|
|
where the effect of the
|
|
.B O
|
|
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.
|
|
See also
|
|
.BR ctime (3).
|
|
.SH "RETURN VALUE"
|
|
The
|
|
.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.
|
|
(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.)
|
|
.LP
|
|
Note that the return value 0 does not necessarily indicate an error;
|
|
for example, in many locales
|
|
.B %p
|
|
yields an empty string.
|
|
.SH ENVIRONMENT
|
|
The environment variables
|
|
.B TZ
|
|
and
|
|
.B LC_TIME
|
|
are used.
|
|
.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
|
|
(marked SU), those given in Olson's timezone package (marked TZ),
|
|
and those given in glibc (marked GNU), except that
|
|
.B %+
|
|
is not supported in glibc2.
|
|
On the other hand glibc2 has several more extensions.
|
|
POSIX.1 only refers to ANSI C; POSIX.2 describes under
|
|
.BR date (1)
|
|
several extensions that could apply to
|
|
.BR strftime ()
|
|
as well.
|
|
The
|
|
.B %F
|
|
conversion is in C99 and POSIX.1-2001.
|
|
|
|
In SUSv2, the
|
|
.B %S
|
|
specifier allowed a range of 00 to 61,
|
|
to allow for the theoretical possibility of a minute that
|
|
included a double leap second
|
|
(there never has been such a minute).
|
|
.SH 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.)
|
|
.\" HP-UX and Tru64 also have features like this.
|
|
Between the \(aq%\(aq character and the conversion specifier character,
|
|
an optional
|
|
.I flag
|
|
and field
|
|
.I width
|
|
may be specified.
|
|
(These precede the
|
|
.B E
|
|
or
|
|
.B O
|
|
modifiers, if present.)
|
|
|
|
The following flag characters are permitted:
|
|
.TP
|
|
.B _
|
|
(underscore)
|
|
Pad a numeric result string with spaces.
|
|
.TP
|
|
.B \-
|
|
(dash)
|
|
Do not pad a numeric result string.
|
|
.TP
|
|
.B 0
|
|
Pad a numeric result string with zeros even if the conversion
|
|
specifier character uses space-padding by default.
|
|
.TP
|
|
.B ^
|
|
Convert alphabetic characters in result string to upper case.
|
|
.TP
|
|
.B #
|
|
Swap the case of the result string.
|
|
(This flag only works with certain conversion specifier characters,
|
|
and of these, it is only really useful with
|
|
.BR %Z .)
|
|
.PP
|
|
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
|
|
Some buggy versions of
|
|
.BR gcc (1)
|
|
complain about the use of
|
|
.BR %c :
|
|
.IR "warning: `%c' yields only last 2 digits of year in some locales" .
|
|
Of course programmers are encouraged to use
|
|
.BR %c ,
|
|
it gives the preferred date and time representation.
|
|
One meets all kinds of strange obfuscations
|
|
to circumvent this
|
|
.BR gcc (1)
|
|
problem.
|
|
A relatively clean one is to add an
|
|
intermediate function
|
|
.in +4n
|
|
.nf
|
|
|
|
size_t
|
|
my_strftime(char *s, size_t max, const char *fmt,
|
|
const struct tm *tm)
|
|
{
|
|
return strftime(s, max, fmt, tm);
|
|
}
|
|
.fi
|
|
.in
|
|
|
|
Nowadays,
|
|
.BR gcc (1)
|
|
provides the \fI\-Wno\-format\-y2k\fP option to prevent the warning,
|
|
so that the above workaround is no longer required.
|
|
.SH EXAMPLE
|
|
The program below can be used to experiment with
|
|
.BR strftime ().
|
|
.nf
|
|
|
|
#include <time.h>
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
|
|
int
|
|
main(int argc, char *argv[])
|
|
{
|
|
char outstr[200];
|
|
time_t t;
|
|
struct tm *tmp;
|
|
|
|
t = time(NULL);
|
|
tmp = localtime(&t);
|
|
if (tmp == NULL) {
|
|
perror("localtime");
|
|
exit(EXIT_FAILURE);
|
|
}
|
|
|
|
if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
|
|
fprintf(stderr, "strftime returned 0");
|
|
exit(EXIT_FAILURE);
|
|
}
|
|
|
|
printf("Result string is \\"%s\\"\\n", outstr);
|
|
exit(EXIT_SUCCESS);
|
|
} /* main */
|
|
.fi
|
|
.PP
|
|
Some examples of the result string produced by the glibc implementation of
|
|
.BR strftime ()
|
|
are as follows:
|
|
.nf
|
|
|
|
$ ./a.out "%m"
|
|
Result string is "11"
|
|
$ ./a.out "%5m"
|
|
Result string is "00011"
|
|
$ ./a.out "%_5m"
|
|
Result string is " 11"
|
|
.fi
|
|
.SH "SEE ALSO"
|
|
.BR date (1),
|
|
.BR time (2),
|
|
.BR ctime (3),
|
|
.BR setlocale (3),
|
|
.BR sprintf (3),
|
|
.BR strptime (3)
|