386 lines
13 KiB
HTML
386 lines
13 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>strptime</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="strptime"></a> <a name="tag_03_736"></a><!-- strptime -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_736_01"></a>NAME</h4>
|
|
|
|
<blockquote>strptime - date and time conversion</blockquote>
|
|
|
|
<h4><a name="tag_03_736_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> #include <<a href="../basedefs/time.h.html">time.h</a>><br>
|
|
<br>
|
|
char *strptime(const char *restrict</tt> <i>buf</i><tt>, const char *restrict</tt> <i>format</i><tt>,<br>
|
|
struct tm *restrict</tt> <i>tm</i><tt>); <img src="../images/opt-end.gif" alt="[Option End]"
|
|
border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
</tt></blockquote>
|
|
|
|
<h4><a name="tag_03_736_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>strptime</i>() function shall convert the character string pointed to by <i>buf</i> to values which are stored in the
|
|
<b>tm</b> structure pointed to by <i>tm</i>, using the format specified by <i>format</i>.</p>
|
|
|
|
<p>The <i>format</i> is composed of zero or more directives. Each directive is composed of one of the following: one or more
|
|
white-space characters (as specified by <a href="../functions/isspace.html"><i>isspace</i>()</a>); an ordinary character (neither
|
|
<tt>'%'</tt> nor a white-space character); or a conversion specification. Each conversion specification is composed of a
|
|
<tt>'%'</tt> character followed by a conversion character which specifies the replacement required. The application shall ensure
|
|
that there is white-space or other non-alphanumeric characters between any two conversion specifications. The following conversion
|
|
specifications are supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><tt>%a</tt></dt>
|
|
|
|
<dd>The day of the week, using the locale's weekday names; either the abbreviated or full name may be specified.</dd>
|
|
|
|
<dt><tt>%A</tt></dt>
|
|
|
|
<dd>Equivalent to <tt>%a</tt> .</dd>
|
|
|
|
<dt><tt>%b</tt></dt>
|
|
|
|
<dd>The month, using the locale's month names; either the abbreviated or full name may be specified.</dd>
|
|
|
|
<dt><tt>%B</tt></dt>
|
|
|
|
<dd>Equivalent to <tt>%b</tt> .</dd>
|
|
|
|
<dt><tt>%c</tt></dt>
|
|
|
|
<dd>Replaced by the locale's appropriate date and time representation.</dd>
|
|
|
|
<dt><tt>%C</tt></dt>
|
|
|
|
<dd>The century number [00,99]; leading zeros are permitted but not required.</dd>
|
|
|
|
<dt><tt>%d</tt></dt>
|
|
|
|
<dd>The day of the month [01,31]; leading zeros are permitted but not required.</dd>
|
|
|
|
<dt><tt>%D</tt></dt>
|
|
|
|
<dd>The date as <tt>%m</tt> / <tt>%d</tt> / <tt>%y</tt> .</dd>
|
|
|
|
<dt><tt>%e</tt></dt>
|
|
|
|
<dd>Equivalent to <tt>%d</tt> .</dd>
|
|
|
|
<dt><tt>%h</tt></dt>
|
|
|
|
<dd>Equivalent to <tt>%b</tt> .</dd>
|
|
|
|
<dt><tt>%H</tt></dt>
|
|
|
|
<dd>The hour (24-hour clock) [00,23]; leading zeros are permitted but not required.</dd>
|
|
|
|
<dt><tt>%I</tt></dt>
|
|
|
|
<dd>The hour (12-hour clock) [01,12]; leading zeros are permitted but not required.</dd>
|
|
|
|
<dt><tt>%j</tt></dt>
|
|
|
|
<dd>The day number of the year [001,366]; leading zeros are permitted but not required.</dd>
|
|
|
|
<dt><tt>%m</tt></dt>
|
|
|
|
<dd>The month number [01,12]; leading zeros are permitted but not required.</dd>
|
|
|
|
<dt><tt>%M</tt></dt>
|
|
|
|
<dd>The minute [00,59]; leading zeros are permitted but not required.</dd>
|
|
|
|
<dt><tt>%n</tt></dt>
|
|
|
|
<dd>Any white space.</dd>
|
|
|
|
<dt><tt>%p</tt></dt>
|
|
|
|
<dd>The locale's equivalent of a.m or p.m.</dd>
|
|
|
|
<dt><tt>%r</tt></dt>
|
|
|
|
<dd>12-hour clock time using the AM/PM notation if <b>t_fmt_ampm</b> is not an empty string in the LC_TIME portion of the current
|
|
locale; in the POSIX locale, this shall be equivalent to <tt>%I</tt> : <tt>%M</tt> : <tt>%S</tt> <tt>%p</tt> .</dd>
|
|
|
|
<dt><tt>%R</tt></dt>
|
|
|
|
<dd>The time as <tt>%H</tt> : <tt>%M</tt> .</dd>
|
|
|
|
<dt><tt>%S</tt></dt>
|
|
|
|
<dd>The seconds [00,60]; leading zeros are permitted but not required.</dd>
|
|
|
|
<dt><tt>%t</tt></dt>
|
|
|
|
<dd>Any white space.</dd>
|
|
|
|
<dt><tt>%T</tt></dt>
|
|
|
|
<dd>The time as <tt>%H</tt> : <tt>%M</tt> : <tt>%S</tt> .</dd>
|
|
|
|
<dt><tt>%U</tt></dt>
|
|
|
|
<dd>The week number of the year (Sunday as the first day of the week) as a decimal number [00,53]; leading zeros are permitted but
|
|
not required.</dd>
|
|
|
|
<dt><tt>%w</tt></dt>
|
|
|
|
<dd>The weekday as a decimal number [0,6], with 0 representing Sunday; leading zeros are permitted but not required.</dd>
|
|
|
|
<dt><tt>%W</tt></dt>
|
|
|
|
<dd>The week number of the year (Monday as the first day of the week) as a decimal number [00,53]; leading zeros are permitted but
|
|
not required.</dd>
|
|
|
|
<dt><tt>%x</tt></dt>
|
|
|
|
<dd>The date, using the locale's date format.</dd>
|
|
|
|
<dt><tt>%X</tt></dt>
|
|
|
|
<dd>The time, using the locale's time format.</dd>
|
|
|
|
<dt><tt>%y</tt></dt>
|
|
|
|
<dd>The year within century. When a century is not otherwise specified, values in the range [69,99] shall refer to years 1969 to
|
|
1999 inclusive, and values in the range [00,68] shall refer to years 2000 to 2068 inclusive; leading zeros shall be permitted but
|
|
shall not be required. <basefont size="2">
|
|
|
|
<dl>
|
|
<dt><b>Note:</b></dt>
|
|
|
|
<dd>It is expected that in a future version of IEEE Std 1003.1-2001 the default century inferred from a 2-digit year will
|
|
change. (This would apply to all commands accepting a 2-digit year as input.)</dd>
|
|
</dl>
|
|
|
|
<basefont size="3"></dd>
|
|
|
|
<dt><tt>%Y</tt></dt>
|
|
|
|
<dd>The year, including the century (for example, 1988).</dd>
|
|
|
|
<dt><tt>%%</tt></dt>
|
|
|
|
<dd>Replaced by <tt>%</tt> .</dd>
|
|
</dl>
|
|
|
|
<h5><a name="tag_03_736_03_01"></a>Modified Conversion Specifiers</h5>
|
|
|
|
<p>Some conversion specifiers can be modified by the <tt>E</tt> and <tt>O</tt> modifier characters to indicate that an alternative
|
|
format or specification should be used rather than the one normally used by the unmodified conversion specifier. If the alternative
|
|
format or specification does not exist in the current locale, the behavior shall be as if the unmodified conversion specification
|
|
were used.</p>
|
|
|
|
<dl compact>
|
|
<dt><tt>%Ec</tt></dt>
|
|
|
|
<dd>The locale's alternative appropriate date and time representation.</dd>
|
|
|
|
<dt><tt>%EC</tt></dt>
|
|
|
|
<dd>The name of the base year (period) in the locale's alternative representation.</dd>
|
|
|
|
<dt><tt>%Ex</tt></dt>
|
|
|
|
<dd>The locale's alternative date representation.</dd>
|
|
|
|
<dt><tt>%EX</tt></dt>
|
|
|
|
<dd>The locale's alternative time representation.</dd>
|
|
|
|
<dt><tt>%Ey</tt></dt>
|
|
|
|
<dd>The offset from <tt>%EC</tt> (year only) in the locale's alternative representation.</dd>
|
|
|
|
<dt><tt>%EY</tt></dt>
|
|
|
|
<dd>The full alternative year representation.</dd>
|
|
|
|
<dt><tt>%Od</tt></dt>
|
|
|
|
<dd>The day of the month using the locale's alternative numeric symbols; leading zeros are permitted but not required.</dd>
|
|
|
|
<dt><tt>%Oe</tt></dt>
|
|
|
|
<dd>Equivalent to <tt>%Od</tt> .</dd>
|
|
|
|
<dt><tt>%OH</tt></dt>
|
|
|
|
<dd>The hour (24-hour clock) using the locale's alternative numeric symbols.</dd>
|
|
|
|
<dt><tt>%OI</tt></dt>
|
|
|
|
<dd>The hour (12-hour clock) using the locale's alternative numeric symbols.</dd>
|
|
|
|
<dt><tt>%Om</tt></dt>
|
|
|
|
<dd>The month using the locale's alternative numeric symbols.</dd>
|
|
|
|
<dt><tt>%OM</tt></dt>
|
|
|
|
<dd>The minutes using the locale's alternative numeric symbols.</dd>
|
|
|
|
<dt><tt>%OS</tt></dt>
|
|
|
|
<dd>The seconds using the locale's alternative numeric symbols.</dd>
|
|
|
|
<dt><tt>%OU</tt></dt>
|
|
|
|
<dd>The week number of the year (Sunday as the first day of the week) using the locale's alternative numeric symbols.</dd>
|
|
|
|
<dt><tt>%Ow</tt></dt>
|
|
|
|
<dd>The number of the weekday (Sunday=0) using the locale's alternative numeric symbols.</dd>
|
|
|
|
<dt><tt>%OW</tt></dt>
|
|
|
|
<dd>The week number of the year (Monday as the first day of the week) using the locale's alternative numeric symbols.</dd>
|
|
|
|
<dt><tt>%Oy</tt></dt>
|
|
|
|
<dd>The year (offset from <tt>%C</tt> ) using the locale's alternative numeric symbols.</dd>
|
|
</dl>
|
|
|
|
<p>A conversion specification composed of white-space characters is executed by scanning input up to the first character that is
|
|
not white-space (which remains unscanned), or until no more characters can be scanned.</p>
|
|
|
|
<p>A conversion specification that is an ordinary character is executed by scanning the next character from the buffer. If the
|
|
character scanned from the buffer differs from the one comprising the directive, the directive fails, and the differing and
|
|
subsequent characters remain unscanned.</p>
|
|
|
|
<p>A series of conversion specifications composed of <tt>%n</tt> , <tt>%t</tt> , white-space characters, or any combination is
|
|
executed by scanning up to the first character that is not white space (which remains unscanned), or until no more characters can
|
|
be scanned.</p>
|
|
|
|
<p>Any other conversion specification is executed by scanning characters until a character matching the next directive is scanned,
|
|
or until no more characters can be scanned. These characters, except the one matching the next directive, are then compared to the
|
|
locale values associated with the conversion specifier. If a match is found, values for the appropriate <b>tm</b> structure members
|
|
are set to values corresponding to the locale information. Case is ignored when matching items in <i>buf</i> such as month or
|
|
weekday names. If no match is found, <i>strptime</i>() fails and no more characters are scanned.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_736_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, <i>strptime</i>() shall return a pointer to the character following the last character parsed.
|
|
Otherwise, a null pointer shall be returned.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_736_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>No errors are defined.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_736_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_736_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>Several "equivalent to" formats and the special processing of white-space characters are provided in order to ease the use of
|
|
identical <i>format</i> strings for <a href="../functions/strftime.html"><i>strftime</i>()</a> and <i>strptime</i>().</p>
|
|
|
|
<p>Applications should use <tt>%Y</tt> (4-digit years) in preference to <tt>%y</tt> (2-digit years).</p>
|
|
|
|
<p>It is unspecified whether multiple calls to <i>strptime</i>() using the same <b>tm</b> structure will update the current
|
|
contents of the structure or overwrite all contents of the structure. Conforming applications should make a single call to
|
|
<i>strptime</i>() with a format and all data needed to completely specify the date and time being converted.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_736_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_736_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>strptime</i>() function is expected to be mandatory in the next version of this volume of
|
|
IEEE Std 1003.1-2001.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_736_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="scanf.html"><i>scanf</i>()</a> , <a href="strftime.html"><i>strftime</i>()</a> , <a href="time.html"><i>time</i>()</a>
|
|
, the Base Definitions volume of IEEE Std 1003.1-2001, <a href="../basedefs/time.h.html"><i><time.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_736_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 4.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_736_12"></a>Issue 5</h4>
|
|
|
|
<blockquote>
|
|
<p>Moved from ENHANCED I18N to BASE.</p>
|
|
|
|
<p>The [ENOSYS] error is removed.</p>
|
|
|
|
<p>The exact meaning of the <tt>%y</tt> and <tt>%Oy</tt> specifiers is clarified in the DESCRIPTION.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_736_13"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The Open Group Corrigendum U033/5 is applied. The <tt>%r</tt> specifier description is reworded.</p>
|
|
|
|
<p>The DESCRIPTION is updated to avoid use of the term "must" for application requirements.</p>
|
|
|
|
<p>The <b>restrict</b> keyword is added to the <i>strptime</i>() prototype for alignment with the ISO/IEC 9899:1999
|
|
standard.</p>
|
|
|
|
<p>The Open Group Corrigendum U047/2 is applied.</p>
|
|
|
|
<p>The DESCRIPTION is updated to use the terms "conversion specifier" and "conversion specification" for consistency with <a
|
|
href="../functions/strftime.html"><i>strftime</i>()</a>.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|