| .\" 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) |