1 STRFTIME(3C)             Standard C Library Functions             STRFTIME(3C)
   2 
   3 
   4 
   5 NAME
   6        strftime, strftime_l, cftime, ascftime - convert date and time to
   7        string
   8 
   9 SYNOPSIS
  10        #include <time.h>
  11 
  12        size_t strftime(char *restrict s, size_t maxsize,
  13             const char *restrict format,
  14             const struct tm *restrict timeptr);
  15 
  16        size_t strftime_l(char *restrict s, size_t maxsize,
  17             const char *restrict format,
  18             const struct tm *restrict timeptr, locale_t loc);
  19 
  20        int cftime(char *s, char *format, const time_t *clock);
  21 
  22        int ascftime(char *s, const char *format,
  23             const struct tm *timeptr);
  24 
  25 
  26 DESCRIPTION
  27        The strftime(), strftime_l(), ascftime(), and cftime() functions place
  28        bytes into the array pointed to by s as controlled by the string
  29        pointed to by format. The format string consists of zero or more
  30        conversion specifications and ordinary characters.  A conversion
  31        specification consists of a '%' (percent) character and one or two
  32        terminating conversion characters that determine the conversion
  33        specification's behavior.  All ordinary characters (including the
  34        terminating null byte) are copied unchanged into the array pointed to
  35        by s. If copying takes place between objects that overlap, the behavior
  36        is undefined. For strftime(), no more than maxsize bytes are placed
  37        into the array. The strftime_l() function behaves identically to
  38        strftime() function, but instead of operating in the current locale, it
  39        operates in the locale specified by loc.
  40 
  41        If format is NULL, then the locale's default format is used.  For
  42        strftime() the default format is the same as %c; for cftime() and
  43        ascftime() the default format is the same as %+.  cftime() and
  44        ascftime() first try to use the value of the environment variable
  45        CFTIME, and if that is undefined or empty, the default format is used.
  46 
  47        Each conversion specification is replaced by appropriate characters as
  48        described in the following list. The appropriate characters are
  49        determined by the LC_TIME category of the program's locale and by the
  50        values contained in the structure pointed to by timeptr for strftime()
  51        and ascftime(), and by the time represented by clock for cftime().
  52 
  53        %%
  54              Same as %.
  55 
  56 
  57        %a
  58              Locale's abbreviated weekday name.
  59 
  60 
  61        %A
  62              Locale's full weekday name.
  63 
  64 
  65        %b
  66              Locale's abbreviated month name.
  67 
  68 
  69        %B
  70              Locale's full month name.
  71 
  72 
  73        %c
  74              Locale's appropriate date and time representation.  In the C
  75              locale, this format is:
  76 
  77                %a %b %e %H:%M:%S %Y
  78 
  79              Other locales may have different locale-specific formats.
  80 
  81 
  82        %C
  83              Century number (the year divided by 100 and truncated to an
  84              integer as a decimal number [01,99]).
  85 
  86 
  87        %d
  88              Day of month [01,31].
  89 
  90 
  91        %D
  92              Date as %m/%d/%y.
  93 
  94 
  95        %e
  96              Day of month [1,31]; single  digits are preceded by a space.
  97 
  98 
  99        %F
 100              Equivalent to %Y-%m-%d (the ISO 8601:2000 standard date format).
 101 
 102 
 103        %g
 104              Week-based year within century [00,99].
 105 
 106 
 107        %G
 108              Week-based year, including the century [0000,9999].
 109 
 110 
 111        %h
 112              Locale's abbreviated month name.
 113 
 114 
 115        %H
 116              Hour (24-hour clock) [00,23].
 117 
 118 
 119        %I
 120              Hour (12-hour clock) [01,12].
 121 
 122 
 123        %j
 124              Day number of year [001,366].
 125 
 126 
 127        %k
 128              Hour (24-hour clock) [0,23]; single digits are preceded by a
 129              space.
 130 
 131 
 132        %l
 133              Hour (12-hour clock) [1,12]; single digits are preceded by a
 134              space.
 135 
 136 
 137        %m
 138              Month number [01,12].
 139 
 140 
 141        %M
 142              Minute [00,59].
 143 
 144 
 145        %n
 146              Insert a NEWLINE.
 147 
 148 
 149        %p
 150              Locale's equivalent of either a.m. or p.m.
 151 
 152 
 153        %r
 154              Appropriate time representation in 12-hour clock format with %p.
 155 
 156 
 157        %R
 158              Time as %H:%M.
 159 
 160 
 161        %s
 162              Seconds since 00:00:00 UTC, January 1, 1970.
 163 
 164 
 165        %S
 166              Seconds [00,60]; the range of values is [00,60] rather than
 167              [00,59] to allow for the occasional leap second.
 168 
 169 
 170        %t
 171              Insert a TAB.
 172 
 173 
 174        %T
 175              Time as %H:%M:%S.
 176 
 177 
 178        %u
 179              Weekday as a decimal number [1,7], with 1 representing Monday.
 180              See NOTES below.
 181 
 182 
 183        %U
 184              Week number of year as a decimal number [00,53], with Sunday as
 185              the first day of week 1.
 186 
 187 
 188        %v
 189              Date as %e-%b-%Y.
 190 
 191 
 192        %V
 193              The ISO 8601 week number as a decimal number [01,53]. In the ISO
 194              8601 week-based system, weeks begin on a Monday and week 1 of the
 195              year is the week that includes both January 4th and the first
 196              Thursday of the year.  If the first Monday of January is the 2nd,
 197              3rd, or 4th, the preceding days are part of the last week of the
 198              preceding year.  See NOTES below.
 199 
 200 
 201        %w
 202              Weekday as a decimal number [0,6], with 0 representing Sunday.
 203 
 204 
 205        %W
 206              Week number of year as a decimal number [00,53], with Monday as
 207              the first day of week 1.
 208 
 209 
 210        %x
 211              Locale's appropriate date representation.
 212 
 213 
 214        %X
 215              Locale's appropriate time representation.
 216 
 217 
 218        %y
 219              Year within century [00,99].
 220 
 221 
 222        %Y
 223              Year, including the century (for example 1993).
 224 
 225 
 226        %z
 227              Replaced by offset from UTC in ISO 8601:2000 standard format
 228              (+hhmm or -hhmm), or by no characters if no time zone is
 229              determinable. For example, "-0430" means 4 hours 30 minutes
 230              behind UTC (west of Greenwich). If tm_isdst is zero, the standard
 231              time offset is used.  If tm_isdst is greater than zero, the
 232              daylight savings time offset if used. If tm_isdst is negative, no
 233              characters are returned.
 234 
 235 
 236        %Z
 237              Time zone name or abbreviation, or no bytes if no time zone
 238              information exists.
 239 
 240 
 241        %+
 242              Locale's date and time representation as produced by date(1).
 243 
 244 
 245        If a conversion specification does not correspond to any of the above
 246        or to any of the modified conversion specifications listed below, the
 247        behavior is undefined and 0 is returned.
 248 
 249        The difference between %U and %W (and also between modified conversion
 250        specifications %OU and %OW) lies in which day is counted as the first
 251        of the week. Week number 1 is the first week in January starting with a
 252        Sunday for %U or a Monday for %W. Week number 0 contains those days
 253        before the first Sunday or Monday in January for %U and %W,
 254        respectively.
 255 
 256    Modified Conversion Specifications
 257        Some conversion specifications can be modified by the E and O modifiers
 258        to indicate that an alternate format or specification should be used
 259        rather than the one normally used by the unmodified conversion
 260        specification.  If the alternate format or specification does not exist
 261        in the current locale, the behavior will be as if the unmodified
 262        specification were used.
 263 
 264        %Ec
 265               Locale's alternate appropriate date and time representation.
 266 
 267 
 268        %EC
 269               Name of the base year (period) in the locale's alternate
 270               representation.
 271 
 272 
 273        %Eg
 274               Offset from %EC of the week-based year in the locale's
 275               alternative representation.
 276 
 277 
 278        %EG
 279               Full alternative representation of the week-based year.
 280 
 281 
 282        %Ex
 283               Locale's alternate date representation.
 284 
 285 
 286        %EX
 287               Locale's alternate time representation.
 288 
 289 
 290        %Ey
 291               Offset from %EC (year only) in the locale's alternate
 292               representation.
 293 
 294 
 295        %EY
 296               Full alternate year representation.
 297 
 298 
 299        %Od
 300               Day of the month using the locale's alternate numeric symbols.
 301 
 302 
 303        %Oe
 304               Same as %Od.
 305 
 306 
 307        %Og
 308               Week-based year (offset from %C) in the locale's alternate
 309               representation and using the locale's alternate numeric symbols.
 310 
 311 
 312        %OH
 313               Hour (24-hour clock) using the locale's alternate numeric
 314               symbols.
 315 
 316 
 317        %OI
 318               Hour (12-hour clock) using the locale's alternate numeric
 319               symbols.
 320 
 321 
 322        %Om
 323               Month using the locale's alternate numeric symbols.
 324 
 325 
 326        %OM
 327               Minutes using the locale's alternate numeric symbols.
 328 
 329 
 330        %OS
 331               Seconds using the locale's alternate numeric symbols.
 332 
 333 
 334        %Ou
 335               Weekday as a number in the locale's alternate numeric symbols.
 336 
 337 
 338        %OU
 339               Week number of the year (Sunday as the first day of the week)
 340               using the locale's alternate numeric symbols.
 341 
 342 
 343        %Ow
 344               Number of the weekday (Sunday=0) using the  locale's alternate
 345               numeric symbols.
 346 
 347 
 348        %OW
 349               Week number of the year (Monday as the first day of the week)
 350               using the locale's alternate numeric symbols.
 351 
 352 
 353        %Oy
 354               Year (offset from %C) in the locale's alternate representation
 355               and using the locale's alternate numeric symbols.
 356 
 357 
 358    Selecting the Output Language
 359        These routines produce output that is formatted according to the
 360        LC_TIME locale category.  They use either the current locale, or in the
 361        case of strftime_l(), the locale supplied by loc.
 362 
 363    Time Zone
 364        Local time zone information is used as though tzset(3C) were called.
 365 
 366 RETURN VALUES
 367        These functions return the number of characters placed into the array
 368        pointed to by s, not including the terminating null character. If the
 369        total number of resulting characters including the terminating null
 370        character is more than maxsize, strftime() returns 0 and the contents
 371        of the array are indeterminate.
 372 
 373 EXAMPLES
 374        Example 1 An example of the strftime() function.
 375 
 376        The following example illustrates the use of strftime() for the POSIX
 377        locale. It shows what the string in str would look like if the
 378        structure pointed to by tmptr contains the values corresponding to
 379        Thursday, August 28, 1986 at 12:44:36.
 380 
 381               strftime(str, strsize, "%A %b %d %j", tmptr);
 382 
 383        This results in str containing "Thursday Aug 28 240".
 384 
 385 ATTRIBUTES
 386        See attributes(5) for descriptions of the following attributes:
 387 
 388        +--------------------+-----------------+
 389        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
 390        +--------------------+-----------------+
 391        |CSI                 | Enabled         |
 392        +--------------------+-----------------+
 393        |Interface Stability | See below.      |
 394        +--------------------+-----------------+
 395        |MT-Level            | MT-Safe         |
 396        +--------------------+-----------------+
 397        |Standard            | See below.      |
 398        +--------------------+-----------------+
 399 
 400        The strftime() and strftime_l() functions are Standard.  cftime() and
 401        ascftime() functions are Committed.
 402 
 403        For strftime() and strftime_l(), see standards(5).
 404 
 405 SEE ALSO
 406        date(1), ctime(3C), mktime(3C), newlocale(3C), setlocale(3C),
 407        strptime(3C), tzset(3C), uselocale(3C), TIMEZONE(4), zoneinfo(4),
 408        attributes(5), environ(5), standards(5)
 409 
 410 NOTES
 411        The conversion specification for %V was changed in the Solaris 7
 412        release.  This change was based on the public review draft of the ISO
 413        C9x standard at that time. Previously, the specification stated that if
 414        the week containing 1 January had fewer than four days in the new year,
 415        it became week 53 of the previous year. The ISO C9x standard committee
 416        subsequently recognized that that specification had been incorrect.
 417 
 418        The conversion specifications for %g, %G, %Eg, %EG, and %Og were added
 419        in the Solaris 7 release.  This change was based on the public review
 420        draft of the ISO C9x standard at that time. The %g and %G
 421        specifications were adopted in the formal standard.  The other two were
 422        not, and should not be used in portable applications.
 423 
 424        The conversion specification for %u was changed in the Solaris 8
 425        release.  This change was based on the XPG4 specification.
 426 
 427        If using the %Z specifier and zoneinfo timezones and if the input date
 428        is outside the range 20:45:52 UTC, December  13, 1901 to 03:14:07 UTC,
 429        January 19, 2038, the timezone name may not be correct.
 430 
 431        The conversion specification for %+ was added in illumos.  It is not
 432        part of any standard, although it is available on a number of other
 433        platforms.  Its use is discouraged for conforming applications.
 434 
 435 
 436 
 437                                 August 20, 2019                   STRFTIME(3C)