| .\" Copyright 1993 Mitchum DSouza <m.dsouza@mrc-apu.cam.ac.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. |
| .\" |
| .\" 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. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Modified, jmv@lucifer.dorms.spbu.ru, 1999-11-08 |
| .\" Modified, aeb, 2000-04-07 |
| .\" Updated from glibc docs, C. Scott Ananian, 2001-08-25 |
| .\" Modified, aeb, 2001-08-31 |
| .\" Modified, wharms 2001-11-12, remark on white space and example |
| .\" |
| .TH STRPTIME 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| strptime \- convert a string representation of time to a time tm structure |
| .SH SYNOPSIS |
| .BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" |
| .br |
| .B #include <time.h> |
| .PP |
| .BI "char *strptime(const char *" s ", const char *" format , |
| .BI "struct tm *" tm ); |
| .SH DESCRIPTION |
| The |
| .BR strptime () |
| function is the converse of |
| .BR strftime (3); |
| it converts the character string pointed to by |
| .I s |
| to values which are stored in the |
| "broken-down time" |
| structure pointed to by |
| .IR tm , |
| using the format specified by |
| .IR format . |
| .PP |
| The broken-down time structure |
| .I tm |
| is defined in |
| .IR <time.h> |
| as follows: |
| .PP |
| .in +4n |
| .EX |
| struct tm { |
| int tm_sec; /* Seconds (0\-60) */ |
| int tm_min; /* Minutes (0\-59) */ |
| int tm_hour; /* Hours (0\-23) */ |
| int tm_mday; /* Day of the month (1\-31) */ |
| int tm_mon; /* Month (0\-11) */ |
| int tm_year; /* Year \- 1900 */ |
| int tm_wday; /* Day of the week (0\-6, Sunday = 0) */ |
| int tm_yday; /* Day in the year (0\-365, 1 Jan = 0) */ |
| int tm_isdst; /* Daylight saving time */ |
| }; |
| .EE |
| .in |
| .PP |
| For more details on the |
| .I tm |
| structure, see |
| .BR ctime (3). |
| .PP |
| The |
| .I format |
| argument |
| is a character string that consists of field descriptors and text characters, |
| reminiscent of |
| .BR scanf (3). |
| Each field descriptor consists of a |
| .B % |
| character followed by another character that specifies the replacement |
| for the field descriptor. |
| All other characters in the |
| .I format |
| string must have a matching character in the input string, |
| except for whitespace, which matches zero or more |
| whitespace characters in the input string. |
| There should be white\%space or other alphanumeric characters |
| between any two field descriptors. |
| .PP |
| The |
| .BR strptime () |
| function processes the input string from left |
| to right. |
| Each of the three possible input elements (whitespace, |
| literal, or format) are handled one after the other. |
| If the input cannot be matched to the format string, the function stops. |
| The remainder of the format and input strings are not processed. |
| .PP |
| The supported input field descriptors are listed below. |
| In case a text string (such as the name of a day of the week or a month name) |
| is to be matched, the comparison is case insensitive. |
| In case a number is to be matched, leading zeros are |
| permitted but not required. |
| .TP |
| .B %% |
| The |
| .B % |
| character. |
| .TP |
| .BR %a " or " %A |
| The name of the day of the week according to the current locale, |
| in abbreviated form or the full name. |
| .TP |
| .BR %b " or " %B " or " %h |
| The month name according to the current locale, |
| in abbreviated form or the full name. |
| .TP |
| .B %c |
| The date and time representation for the current locale. |
| .TP |
| .B %C |
| The century number (0\(en99). |
| .TP |
| .BR %d " or " %e |
| The day of month (1\(en31). |
| .TP |
| .B %D |
| Equivalent to |
| .BR %m/%d/%y . |
| (This is the American style date, very confusing |
| to non-Americans, especially since |
| .B %d/%m/%y |
| is widely used in Europe. |
| The ISO 8601 standard format is |
| .BR %Y-%m-%d .) |
| .TP |
| .B %H |
| The hour (0\(en23). |
| .TP |
| .B %I |
| The hour on a 12-hour clock (1\(en12). |
| .TP |
| .B %j |
| The day number in the year (1\(en366). |
| .TP |
| .B %m |
| The month number (1\(en12). |
| .TP |
| .B %M |
| The minute (0\(en59). |
| .TP |
| .B %n |
| Arbitrary whitespace. |
| .TP |
| .B %p |
| The locale's equivalent of AM or PM. |
| (Note: there may be none.) |
| .TP |
| .B %r |
| The 12-hour clock time (using the locale's AM or PM). |
| In the POSIX locale equivalent to |
| .BR "%I:%M:%S %p" . |
| If |
| .I t_fmt_ampm |
| is empty in the |
| .B LC_TIME |
| part of the current locale, |
| then the behavior is undefined. |
| .TP |
| .B %R |
| Equivalent to |
| .BR %H:%M . |
| .TP |
| .B %S |
| The second (0\(en60; 60 may occur for leap seconds; |
| earlier also 61 was allowed). |
| .TP |
| .B %t |
| Arbitrary whitespace. |
| .TP |
| .B %T |
| Equivalent to |
| .BR %H:%M:%S . |
| .TP |
| .B %U |
| The week number with Sunday the first day of the week (0\(en53). |
| The first Sunday of January is the first day of week 1. |
| .TP |
| .B %w |
| The ordinal number of the day of the week (0\(en6), with Sunday = 0. |
| .TP |
| .B %W |
| The week number with Monday the first day of the week (0\(en53). |
| The first Monday of January is the first day of week 1. |
| .TP |
| .B %x |
| The date, using the locale's date format. |
| .TP |
| .B %X |
| The time, using the locale's time format. |
| .TP |
| .B %y |
| The year within century (0\(en99). |
| When a century is not otherwise specified, values in the range 69\(en99 refer |
| to years in the twentieth century (1969\(en1999); values in the |
| range 00\(en68 refer to years in the twenty-first century (2000\(en2068). |
| .TP |
| .B %Y |
| The year, including century (for example, 1991). |
| .PP |
| Some field descriptors can be modified by the E or O modifier characters |
| to indicate that an alternative format or specification should be used. |
| If the |
| alternative format or specification does not exist in the current locale, the |
| unmodified field descriptor is used. |
| .PP |
| The E modifier specifies that the input string may contain |
| alternative locale-dependent versions of the date and time representation: |
| .TP |
| .B %Ec |
| The locale's alternative date and time representation. |
| .TP |
| .B %EC |
| The name of the base year (period) in the locale's alternative representation. |
| .TP |
| .B %Ex |
| The locale's alternative date representation. |
| .TP |
| .B %EX |
| The locale's alternative time representation. |
| .TP |
| .B %Ey |
| The offset from |
| .B %EC |
| (year only) in the locale's alternative representation. |
| .TP |
| .B %EY |
| The full alternative year representation. |
| .PP |
| The O modifier specifies that the numerical input may be in an |
| alternative locale-dependent format: |
| .TP |
| .BR %Od " or " %Oe |
| The day of the month using the locale's alternative numeric symbols; |
| leading zeros are permitted but not required. |
| .TP |
| .B %OH |
| The hour (24-hour clock) using the locale's alternative numeric symbols. |
| .TP |
| .B %OI |
| The hour (12-hour clock) using the locale's alternative numeric symbols. |
| .TP |
| .B %Om |
| The month using the locale's alternative numeric symbols. |
| .TP |
| .B %OM |
| The minutes using the locale's alternative numeric symbols. |
| .TP |
| .B %OS |
| The seconds using the locale's alternative numeric symbols. |
| .TP |
| .B %OU |
| The week number of the year (Sunday as the first day of the week) |
| using the locale's alternative numeric symbols. |
| .TP |
| .B %Ow |
| The ordinal number of the day of the week (Sunday=0), |
| using the locale's alternative numeric symbols. |
| .TP |
| .B %OW |
| The week number of the year (Monday as the first day of the week) |
| using the locale's alternative numeric symbols. |
| .TP |
| .B %Oy |
| The year (offset from |
| .BR %C ) |
| using the locale's alternative numeric symbols. |
| .SH RETURN VALUE |
| The return value of the function is a pointer to the first character |
| not processed in this function call. |
| In case the input string |
| contains more characters than required by the format string, the return |
| value points right after the last consumed input character. |
| In case the whole input string is consumed, |
| the return value points to the null byte at the end of the string. |
| If |
| .BR strptime () |
| fails to match all |
| of the format string and therefore an error occurred, the function |
| returns NULL. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .TS |
| allbox; |
| lb lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR strptime () |
| T} Thread safety MT-Safe env locale |
| .TE |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, SUSv2. |
| .SH NOTES |
| .PP |
| In principle, this function does not initialize |
| .I tm |
| but |
| stores only the values specified. |
| This means that |
| .I tm |
| should be initialized before the call. |
| Details differ a bit between different UNIX systems. |
| The glibc implementation does not touch those fields which are not |
| explicitly specified, except that it recomputes the |
| .I tm_wday |
| and |
| .I tm_yday |
| field if any of the year, month, or day elements changed. |
| .\" .PP |
| .\" This function is available since libc 4.6.8. |
| .\" Linux libc4 and libc5 includes define the prototype unconditionally; |
| .\" glibc2 includes provide a prototype only when |
| .\" .B _XOPEN_SOURCE |
| .\" or |
| .\" .B _GNU_SOURCE |
| .\" are defined. |
| .\" .PP |
| .\" Before libc 5.4.13 whitespace |
| .\" (and the \(aqn\(aq and \(aqt\(aq specifications) was not handled, |
| .\" no \(aqE\(aq and \(aqO\(aq locale modifier characters were accepted, |
| .\" and the \(aqC\(aq specification was a synonym for the \(aqc\(aq specification. |
| .PP |
| The \(aqy\(aq (year in century) specification is taken to specify a year |
| .\" in the 20th century by libc4 and libc5. |
| .\" It is taken to be a year |
| in the range 1950\(en2049 by glibc 2.0. |
| It is taken to be a year in |
| 1969\(en2068 since glibc 2.1. |
| .\" In libc4 and libc5 the code for %I is broken (fixed in glibc; |
| .\" %OI was fixed in glibc 2.2.4). |
| .SS Glibc notes |
| For reasons of symmetry, glibc tries to support for |
| .BR strptime () |
| the same format characters as for |
| .BR strftime (3). |
| (In most cases, the corresponding fields are parsed, but no field in |
| .I tm |
| is changed.) |
| This leads to |
| .TP |
| .B %F |
| Equivalent to |
| .BR %Y-%m-%d , |
| the ISO 8601 date format. |
| .TP |
| .B %g |
| The year corresponding to the ISO week number, but without the century |
| (0\(en99). |
| .TP |
| .B %G |
| The year corresponding to the ISO week number. |
| (For example, 1991.) |
| .TP |
| .B %u |
| The day of the week as a decimal number (1\(en7, where Monday = 1). |
| .TP |
| .B %V |
| The ISO 8601:1988 week number as a decimal number (1\(en53). |
| If the week (starting on Monday) containing 1 January has four or more days |
| in the new year, then it is considered week 1. |
| Otherwise, it is the last week |
| of the previous year, and the next week is week 1. |
| .TP |
| .B %z |
| An RFC-822/ISO 8601 standard timezone specification. |
| .TP |
| .B %Z |
| The timezone name. |
| .PP |
| Similarly, because of GNU extensions to |
| .BR strftime (3), |
| .B %k |
| is accepted as a synonym for |
| .BR %H , |
| and |
| .B %l |
| should be accepted |
| as a synonym for |
| .BR %I , |
| and |
| .B %P |
| is accepted as a synonym for |
| .BR %p . |
| Finally |
| .TP |
| .B %s |
| The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). |
| Leap seconds are not counted unless leap second support is available. |
| .PP |
| The glibc implementation does not require whitespace between |
| two field descriptors. |
| .SH EXAMPLE |
| The following example demonstrates the use of |
| .BR strptime () |
| and |
| .BR strftime (3). |
| .PP |
| .EX |
| #define _XOPEN_SOURCE |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <string.h> |
| #include <time.h> |
| |
| int |
| main(void) |
| { |
| struct tm tm; |
| char buf[255]; |
| |
| memset(&tm, 0, sizeof(struct tm)); |
| strptime("2001\-11\-12 18:31:01", "%Y\-%m\-%d %H:%M:%S", &tm); |
| strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm); |
| puts(buf); |
| exit(EXIT_SUCCESS); |
| } |
| .EE |
| .SH SEE ALSO |
| .BR time (2), |
| .BR getdate (3), |
| .BR scanf (3), |
| .BR setlocale (3), |
| .BR strftime (3) |