📄 getdate_err.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-2004 IEEE and The Open Group, All Rights Reserved --><title>getdate</title></head><body bgcolor="white"><script type="text/javascript" language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> <a name="getdate"></a> <a name="tag_03_216"></a><!-- getdate --> <!--header start--><center><font size="2">The Open Group Base Specifications Issue 6<br>IEEE Std 1003.1, 2004 Edition<br>Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.</font></center><!--header end--><hr size="2" noshade><h4><a name="tag_03_216_01"></a>NAME</h4><blockquote>getdate - convert user format date and time</blockquote><h4><a name="tag_03_216_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> struct tm *getdate(const char *</tt><i>string</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_216_03"></a>DESCRIPTION</h4><blockquote><p>The <i>getdate</i>() function shall convert a string representation of a date or time into a broken-down time.</p><p>The external variable or macro <i>getdate_err</i> is used by <i>getdate</i>() to return error values.</p><p>Templates are used to parse and interpret the input string. The templates are contained in a text file identified by theenvironment variable <i>DATEMSK .</i> The <i>DATEMSK</i> variable should be set to indicate the full pathname of the file thatcontains the templates. The first line in the template that matches the input specification is used for interpretation andconversion into the internal time format.</p><p>The following conversion specifications shall be supported:</p><dl compact><dt><tt>%%</tt></dt><dd>Equivalent to <tt>%</tt>.</dd><dt><tt>%a</tt></dt><dd>Abbreviated weekday name.</dd><dt><tt>%A</tt></dt><dd>Full weekday name.</dd><dt><tt>%b</tt></dt><dd>Abbreviated month name.</dd><dt><tt>%B</tt></dt><dd>Full month name.</dd><dt><tt>%c</tt></dt><dd>Locale's appropriate date and time representation.</dd><dt><tt>%C</tt></dt><dd>Century number [00,99]; leading zeros are permitted but not required.</dd><dt><tt>%d</tt></dt><dd>Day of month [01,31]; the leading 0 is optional.</dd><dt><tt>%D</tt></dt><dd>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>Abbreviated month name.</dd><dt><tt>%H</tt></dt><dd>Hour [00,23].</dd><dt><tt>%I</tt></dt><dd>Hour [01,12].</dd><dt><tt>%m</tt></dt><dd>Month number [01,12].</dd><dt><tt>%M</tt></dt><dd>Minute [00,59].</dd><dt><tt>%n</tt></dt><dd>Equivalent to <newline>.</dd><dt><tt>%p</tt></dt><dd>Locale's equivalent of either AM or PM.</dd><dt><tt>%r</tt></dt><dd>The locale's appropriate representation of time in AM and PM notation. 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>Time as <tt>%H</tt> : <tt>%M</tt>.</dd><dt><tt>%S</tt></dt><dd>Seconds [00,60]. The range goes to 60 (rather than stopping at 59) to allow positive leap seconds to be expressed. Since leapseconds cannot be predicted by any algorithm, leap second data must come from some external source.</dd><dt><tt>%t</tt></dt><dd>Equivalent to <tab>.</dd><dt><tt>%T</tt></dt><dd>Time as <tt>%H</tt> : <tt>%M</tt> : <tt>%S</tt>.</dd><dt><tt>%w</tt></dt><dd>Weekday number (Sunday = [0,6]).</dd><dt><tt>%x</tt></dt><dd>Locale's appropriate date representation.</dd><dt><tt>%X</tt></dt><dd>Locale's appropriate time representation.</dd><dt><tt>%y</tt></dt><dd>Year within century. When a century is not otherwise specified, values in the range [69,99] shall refer to years 1969 to 1999inclusive, and values in the range [00,68] shall refer to years 2000 to 2068 inclusive. <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 willchange. (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>Year as <tt>"ccyy"</tt> (for example, 2001).</dd><dt><tt>%Z</tt></dt><dd>Timezone name or no characters if no timezone exists. If the timezone supplied by <tt>%Z</tt> is not the timezone that<i>getdate</i>() expects, an invalid input specification error shall result. The <i>getdate</i>() function calculates an expectedtimezone based on information supplied to the function (such as the hour, day, and month).</dd></dl><p>The match between the template and input specification performed by <i>getdate</i>() shall be case-insensitive.</p><p>The month and weekday names can consist of any combination of upper and lowercase letters. The process can request that theinput date or time specification be in a specific language by setting the <i>LC_TIME</i> category (see <a href="setlocale.html"><i>setlocale</i>()</a>).</p><p>Leading zeros are not necessary for the descriptors that allow leading zeros. However, at most two digits are allowed for thosedescriptors, including leading zeros. Extra whitespace in either the template file or in <i>string</i> shall be ignored.</p><p>The results are undefined if the conversion specifications <tt>%c</tt>, <tt>%x</tt>, and <tt>%X</tt> include unsupportedconversion specifications.</p><p>The following rules apply for converting the input specification into the internal format:</p><ul><li><p>If <tt>%Z</tt> is being scanned, then <i>getdate</i>() shall initialize the broken-down time to be the current time in thescanned timezone. Otherwise, it shall initialize the broken-down time based on the current local time as if <a href="../functions/localtime.html"><i>localtime</i>()</a> had been called.</p></li><li><p>If only the weekday is given, the day chosen shall be the day, starting with today and moving into the future, which firstmatches the named day.</p></li><li><p>If only the month (and no year) is given, the month chosen shall be the month, starting with the current month and moving intothe future, which first matches the named month. The first day of the month shall be assumed if no day is given.</p></li><li><p>If no hour, minute, and second are given, the current hour, minute, and second shall be assumed.</p></li><li><p>If no date is given, the hour chosen shall be the hour, starting with the current hour and moving into the future, which firstmatches the named hour.</p></li></ul><p>If a conversion specification in the DATEMSK file does not correspond to one of the conversion specifications above, thebehavior is unspecified.</p><p>The <i>getdate</i>() function need not be reentrant. A function that is not required to be reentrant is not required to bethread-safe.</p></blockquote><h4><a name="tag_03_216_04"></a>RETURN VALUE</h4><blockquote><p>Upon successful completion, <i>getdate</i>() shall return a pointer to a <b>struct tm</b>. Otherwise, it shall return a nullpointer and set <i>getdate_err</i> to indicate the error.</p></blockquote><h4><a name="tag_03_216_05"></a>ERRORS</h4><blockquote><p>The <i>getdate</i>() function shall fail in the following cases, setting <i>getdate_err</i> to the value shown in the listbelow. Any changes to <i>errno</i> are unspecified.</p><ol><li><p>The <i>DATEMSK</i> environment variable is null or undefined.</p></li><li><p>The template file cannot be opened for reading.</p></li><li><p>Failed to get file status information.</p></li><li><p>The template file is not a regular file.</p></li><li><p>An I/O error is encountered while reading the template file.</p></li><li><p>Memory allocation failed (not enough memory available).</p></li><li><p>There is no line in the template that matches the input.</p></li><li><p>Invalid input specification. For example, February 31; or a time is specified that cannot be represented in a <b>time_t</b>(representing the time in seconds since the Epoch).</p></li></ol></blockquote><hr><div class="box"><em>The following sections are informative.</em></div><h4><a name="tag_03_216_06"></a>EXAMPLES</h4><blockquote><ol><li><p>The following example shows the possible contents of a template:</p><pre><tt>%m%A %B %d, %Y, %H:%M:%S%A%B%m/%d/%y %I %p%d,%m,%Y %H:%Mat %A the %dst of %B in %Yrun job at %I %p,%B %dnd%A den %d. %B %Y %H.%M Uhr</tt></pre></li><li><p>The following are examples of valid input specifications for the template in Example 1:</p><pre><tt>getdate("10/1/87 4 PM");getdate("Friday");getdate("Friday September 18, 1987, 10:30:30");getdate("24,9,1986 10:30");getdate("at monday the 1st of december in 1986");getdate("run job at 3 PM, december 2nd");</tt></pre><p>If the <i>LC_TIME</i> category is set to a German locale that includes <i>freitag</i> as a weekday name and <i>oktober</i> as amonth name, the following would be valid:</p><pre><tt>getdate("freitag den 10. oktober 1986 10.30 Uhr");</tt></pre></li><li><p>The following example shows how local date and time specification can be defined in the template:</p>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -