Print this page 
Garrett's man page edits.
Split Close
Expand all
Collapse all
          --- old/usr/src/man/man3c/strptime.3c
          +++ new/usr/src/man/man3c/strptime.3c
   1    1  '\" te
   2    2  .\" Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
   3    3  .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   4    4  .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   5    5  .\" http://www.opengroup.org/bookstore/.
   6    6  .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   7    7  .\"  This notice shall appear on any product containing this material.
   8    8  .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   9    9  .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  10   10  .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  11      -.TH STRPTIME 3C "Aug 27, 2007"
       11 +.TH STRPTIME 3C "Jun 27, 2014"
  12   12  .SH NAME
  13   13  strptime, strptime_l \- date and time conversion
  14   14  .SH SYNOPSIS
  15   15  .LP
  16   16  .nf
  17   17  #include <time.h>
  18   18  
  19   19  \fBchar *\fR\fBstrptime\fR(\fBconst char *restrict\fR \fIbuf\fR,
  20   20       \fBconst char *restrict\fR \fIformat\fR, \fBstruct tm *restrict\fR \fItm\fR);
       21 +.fi
       22 +.LP
       23 +.nf
       24 +#include <time.h>
       25 +#include <xlocale.h>
  21   26  
  22   27  \fBchar *\fR\fBstrptime_l\fR(\fBconst char *restrict\fR \fIbuf\fR,
  23   28       \fBconst char *restrict\fR \fIformat\fR, \fBstruct tm *restrict\fR \fItm\fR,
  24   29       \fBlocale_t\fR \fIloc\fR);
  25   30  .fi
  26      -
  27   31  .SS "Non-zeroing Behavior"
  28   32  .LP
  29   33  .nf
  30   34  \fBcc\fR [\fIflag\fR...]  \fIfile\fR... \fB-D_STRPTIME_DONTZERO\fR [\fIlibrary\fR...]
  31   35  #include <time.h>
  32   36  
  33   37  \fBchar *\fR\fBstrptime\fR(\fBconst char *restrict\fR \fIbuf\fR,
  34   38       \fBconst char *restrict\fR \fIformat\fR, \fBstruct tm *restrict\fR \fItm\fR);
  35   39  .fi
  36   40  
  37   41  .SH DESCRIPTION
  38      -.sp
  39   42  .LP
  40   43  The \fBstrptime()\fR function converts the character string pointed to by
  41   44  \fIbuf\fR to values which are stored in the \fBtm\fR structure pointed to by
  42   45  \fItm\fR, using the format specified by \fIformat\fR. The \fBstrptime_l()\fR
  43   46  function is identical to \fBstrptime()\fR except instead of acting in the
  44   47  current locale, it acts in the locale specified by the argument \fIloc\fR.
  45      -.sp
  46   48  .LP
  47   49  The \fIformat\fR argument is composed of zero or more conversion
  48   50  specifications. Each conversion specification is composed of a "%" (percent)
  49   51  character followed by one or two conversion characters which specify the
  50   52  replacement required. One or more white space characters (as specified by
  51   53  \fBisspace\fR(3C)) may precede or follow a conversion specification. There must
  52   54  be white-space or other non-alphanumeric characters between any two conversion
  53   55  specifications.
  54      -.sp
  55   56  .LP
  56   57  A non-zeroing version of \fBstrptime()\fR, described below under \fBNon-zeroing
  57   58  Behavior\fR, is provided if \fB_STRPTIME_DONTZERO\fR is defined.
  58   59  .SS "Conversion Specifications"
  59      -.sp
  60   60  .LP
  61   61  The following conversion specifications are supported:
  62   62  .sp
  63   63  .ne 2
  64   64  .na
  65   65  \fB\fB%%\fR\fR
  66   66  .ad
  67   67  .RS 6n
  68   68  Same as \fB%\fR.
  69   69  .RE
↓ open down ↓ 289 lines elided ↑ open up ↑ 
 359  359  .sp
 360  360  .ne 2
 361  361  .na
 362  362  \fB\fB%Z\fR\fR
 363  363  .ad
 364  364  .RS 6n
 365  365  Time zone name or no characters if no time zone exists.
 366  366  .RE
 367  367  
 368  368  .SS "Modified Conversion Specifications"
 369      -.sp
 370  369  .LP
 371  370  Some conversion specifications can be modified by the \fBE\fR and \fBO\fR
 372  371  modifier characters to indicate that an alternate format or specification
 373  372  should be used rather than the one normally used by the unmodified
 374  373  specification. If the alternate format or specification does not exist in the
 375  374  current locale, the behavior will be as if the unmodified conversion
 376  375  specification were used.
 377  376  .sp
 378  377  .ne 2
 379  378  .na
↓ open down ↓ 144 lines elided ↑ open up ↑ 
 524  523  .ne 2
 525  524  .na
 526  525  \fB\fB%Oy\fR\fR
 527  526  .ad
 528  527  .RS 7n
 529  528  Year (offset from \fB%C\fR) in the locale's alternate  representation and using
 530  529  the locale's alternate numeric symbols.
 531  530  .RE
 532  531  
 533  532  .SS "General Specifications"
 534      -.sp
 535  533  .LP
 536  534  A conversion specification that is an ordinary character is executed by
 537  535  scanning the next character from the buffer. If the character scanned from the
 538  536  buffer differs from the one comprising the specification, the specification
 539  537  fails, and the differing and subsequent characters remain unscanned.
 540  538  .sp
 541  539  .LP
 542  540  A series of specifications composed of \fB%n\fR, \fB%t\fR, white-space
 543  541  characters or any combination is executed by scanning up to the first character
 544  542  that is not white space (which remains unscanned), or until no more characters
 545  543  can be scanned.  White space is defined by \fBisspace\fR(3C).
 546      -.sp
 547  544  .LP
 548  545  Any other conversion specification is executed by scanning characters until a
 549  546  character matching the next specification is scanned, or until no more
 550  547  characters can be scanned. These characters, except the one matching the next
 551  548  specification, are then compared to the locale values associated with the
 552  549  conversion specifier.  If a match is found, values for the appropriate
 553  550  \fItm\fR structure members are set to values corresponding to the locale
 554  551  information. If no match is found,  \fBstrptime()\fR fails and no more
 555  552  characters are scanned.
 556  553  .sp
 557  554  .LP
 558  555  The month names, weekday names, era names, and alternate numeric symbols can
 559  556  consist of any combination of upper and lower case letters.  The user can
 560  557  request that the input date or time specification be in a specific language by
 561  558  setting the \fBLC_TIME\fR category using \fBsetlocale\fR(3C).
 562  559  .SS "Non-zeroing Behavior"
 563      -.sp
 564  560  .LP
 565  561  In addition to the behavior described above by various standards, the Solaris
 566  562  implementation of \fBstrptime()\fR provides the following extensions. These may
 567  563  change at any time in the future.  Portable applications should not depend on
 568  564  these extended features:
 569  565  .RS +4
 570  566  .TP
 571  567  .ie t \(bu
 572  568  .el o
 573  569  If \fB_STRPTIME_DONTZERO\fR is not defined, the \fBtm struct\fR is zeroed on
↓ open down ↓ 2 lines elided ↑ open up ↑ 
 576  572  .RE
 577  573  .RS +4
 578  574  .TP
 579  575  .ie t \(bu
 580  576  .el o
 581  577  If \fB_STRPTIME_DONTZERO\fR is defined, \fBstrptime()\fR does not zero the
 582  578  \fBtm struct\fR on entry.  Additionally, for some specifiers, \fBstrptime()\fR
 583  579  will use some values in the input \fBtm struct\fR to recalculate the date and
 584  580  re-assign the appropriate members of the \fBtm struct\fR.
 585  581  .RE
 586      -.sp
 587  582  .LP
 588  583  The following describes extended features regardless of whether
 589  584  \fB_STRPTIME_DONTZERO\fR is defined or not defined:
 590  585  .RS +4
 591  586  .TP
 592  587  .ie t \(bu
 593  588  .el o
 594  589  If \fB%j\fR is specified, \fBtm_yday\fR is set;  if year is given, and if month
 595  590  and day are not given, \fBstrptime()\fR calculates and sets \fBtm_mon\fR,
 596  591  \fBtm_mday\fR, and \fBtm_year\fR.
 597  592  .RE
 598  593  .RS +4
 599  594  .TP
 600  595  .ie t \(bu
 601  596  .el o
 602  597  If \fB%U\fR or \fB%W\fR is specified and if weekday and year are given and
 603  598  month and day of month are not given, \fBstrptime()\fR calculates and sets
 604  599  \fBtm_mon\fR, \fBtm_mday\fR, \fBtm_wday\fR, and \fBtm_year\fR.
 605  600  .RE
 606      -.sp
 607  601  .LP
 608  602  The following describes extended features when \fB_STRPTIME_DONTZERO\fR is not
 609  603  defined:
 610  604  .RS +4
 611  605  .TP
 612  606  .ie t \(bu
 613  607  .el o
 614  608  If \fB%C\fR is specified and \fB%y\fR is not specified, \fBstrptime()\fRassumes
 615  609  0 as the year offset, then calculates the year, and assigns \fBtm_year\fR.
 616  610  .RE
 617      -.sp
 618  611  .LP
 619  612  The following describes extended features when \fB_STRPTIME_DONTZERO\fR is
 620  613  defined:
 621  614  .RS +4
 622  615  .TP
 623  616  .ie t \(bu
 624  617  .el o
 625  618  If \fB%C\fR is specified and \fB%y\fR is not specified, \fBstrptime()\fR
 626  619  assumes the year offset of the year value of the \fBtm_year\fR member of the
 627  620  input \fBtm struct\fR, then calculates the year and assigns \fBtm_year\fR.
↓ open down ↓ 25 lines elided ↑ open up ↑ 
 653  646  .ie t \(bu
 654  647  .el o
 655  648  If \fB%p\fR is specified and if hour is not specified, \fBstrptime()\fR will
 656  649  reference, and if needed, update the \fBtm_hour\fR member. If the \fBam_pm\fR
 657  650  input is p.m. and the input \fBtm_hour\fR value is between 0 - 11,
 658  651  \fBstrptime()\fR will add 12 hours and update \fBtm_hour\fR.  If the
 659  652  \fBam_pm\fR input is a.m. and input \fBtm_hour\fR value is between 12 - 23,
 660  653  \fBstrptime()\fR will subtract 12 hours and update \fBtm_hour\fR.
 661  654  .RE
 662  655  .SH RETURN VALUES
 663      -.sp
 664  656  .LP
 665  657  Upon successful completion, \fBstrptime()\fR returns a pointer to the character
 666  658  following the last character parsed. Otherwise, a null pointer is returned.
 667  659  .SH USAGE
 668      -.sp
 669  660  .LP
 670  661  Several "same as" formats, and the special processing of white-space characters
 671  662  are provided in order to ease the use of identical  \fIformat\fR strings for
 672  663  \fBstrftime\fR(3C) and \fBstrptime()\fR.
 673      -.sp
 674  664  .LP
 675  665  The \fBstrptime()\fR function tries to calculate \fBtm_year\fR, \fBtm_mon\fR,
 676  666  and \fBtm_mday\fR when given incomplete input.  This allows the \fBstruct tm\fR
 677  667  created by \fBstrptime()\fR to be passed to \fBmktime\fR(3C) to produce a
 678  668  \fBtime_t\fR value for dates and times that are representable by a
 679  669  \fBtime_t\fR.  As an example, since \fBmktime()\fR ignores \fBtm_yday\fR,
 680  670  \fBstrptime()\fR calculates \fBtm_mon\fR and \fBtm_mday\fR as well as filling
 681  671  in \fBtm_yday\fR when \fB%j\fR is specified without otherwise specifying a
 682  672  month and day within month.
 683  673  .SH ATTRIBUTES
 684      -.sp
 685  674  .LP
 686  675  See \fBattributes\fR(5) for descriptions of the following attributes:
 687      -.sp
 688      -
 689      -.sp
 690  676  .TS
 691  677  box;
 692  678  c | c
 693  679  l | l .
 694  680  ATTRIBUTE TYPE  ATTRIBUTE VALUE
 695  681  _
 696  682  CSI     Enabled
 697  683  _
 698      -Interface Stability     Committed
      684 +Interface Stability     See below.
 699  685  _
 700  686  MT-Level        MT-Safe
 701  687  _
 702      -Standard        See \fBstandards\fR(5).
      688 +Standard        See \fBstandards\fR(5) for \fBstrptime()\fR.
 703  689  .TE
 704  690  
      691 +.LP
      692 +The \fBstrptime()\fR function is Standard.  The \fBstrptime_l()\fR function
      693 +is Uncommitted.
 705  694  .SH SEE ALSO
 706      -.sp
 707  695  .LP
 708  696  \fBctime\fR(3C), \fBgetdate\fR(3C), \fBisspace\fR(3C), \fBmktime\fR(3C),
 709      -\fBsetlocale\fR(3C), \fBstrftime\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5),
      697 +\fBnewlocale\fR(3C),
      698 +\fBsetlocale\fR(3C), \fBstrftime\fR(3C), \fBuselocale\fR(3C),
      699 +\fBattributes\fR(5), \fBenviron\fR(5),
 710  700  \fBstandards\fR(5)
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX