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