mirror of https://github.com/mkerrisk/man-pages
373 lines
11 KiB
Groff
373 lines
11 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 \fBstrftime\fP() 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 `%'
|
|
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 %m/%d/%y. (Yecch \(em for Americans only.
|
|
Americans should note that in other countries %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 %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 %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 %V).
|
|
This has the same format and value as %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 %G, but without century, i.e., with a 2-digit year (00-99). (TZ)
|
|
.TP
|
|
.B %h
|
|
Equivalent to %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 %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 %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 %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 `%I:%M:%S %p'. (SU)
|
|
.TP
|
|
.B %R
|
|
The time in 24-hour notation (%H:%M). (SU)
|
|
For a version including the seconds, see %T below.
|
|
.TP
|
|
.B %s
|
|
The number of seconds since the Epoch, i.e., 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 (%H:%M:%S). (SU)
|
|
.TP
|
|
.B %u
|
|
The day of the week as a decimal, range 1 to 7, Monday being 1.
|
|
See also %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 %V and %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 %U and %W. (SU)
|
|
.TP
|
|
.B %w
|
|
The day of the week as a decimal, range 0 to 6, Sunday being 0.
|
|
See also %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 `%' character.
|
|
.PP
|
|
Some conversion specifications can be modified by preceding the
|
|
conversion specifier character by the E or 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 behaviour will be as if the unmodified
|
|
conversion specification were used. (SU)
|
|
The Single Unix Specification mentions %Ec, %EC, %Ex, %EX,
|
|
%Ey, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV,
|
|
%Ow, %OW, %Oy, where the effect of the 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 \fBstrftime\fP() 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.
|
|
(Thus at least since 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 %p yields an empty string.
|
|
.SH ENVIRONMENT
|
|
The environment variables TZ and LC_TIME are used.
|
|
.SH "CONFORMING TO"
|
|
ANSI C, SVID 3, ISO 9899.
|
|
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 %+ 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 %F conversion is in C99 and POSIX 1003.1-2001.
|
|
|
|
In SUSv2, the %S specified 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 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 % character and the conversion specifier character,
|
|
an optional
|
|
.I flag
|
|
and field
|
|
.I width
|
|
may be specified.
|
|
(These precede the E or 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 %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 gcc complain about the use of %c:
|
|
.IR "warning: `%c' yields only last 2 digits of year in some locales" .
|
|
Of course programmers are encouraged to use %c, it gives the preferred
|
|
date and time representation. One meets all kinds of strange obfuscations
|
|
to circumvent this gcc problem. A relatively clean one is to add an
|
|
intermediate function
|
|
.RS
|
|
size_t my_strftime(char *s, size_t max, const char *fmt,
|
|
const struct tm *tm) {
|
|
.br
|
|
return strftime(s, max, fmt, tm);
|
|
.br
|
|
}
|
|
.RE
|
|
.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)
|