lib/strftime.h

   1 /* declarations for strftime.c
   2
   3    Copyright (C) 2002, 2004, 2008-2024 Free Software Foundation, Inc.
   4
   5    This file is free software: you can redistribute it and/or modify
   6    it under the terms of the GNU Lesser General Public License as
   7    published by the Free Software Foundation, either version 3 of the
   8    License, or (at your option) any later version.
   9
  10    This file is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public License
  16    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  17
  18 #include <time.h>
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /* Formats the broken-down time *__TP, with additional __NS nanoseconds,
  25    into the buffer __S of size __MAXSIZE, according to the rules of the
  26    LC_TIME category of the current locale.
  27
  28    Uses the time zone __TZ.
  29    If *__TP represents local time, __TZ should be set to
  30      tzalloc (getenv ("TZ")).
  31    If *__TP represents universal time (a.k.a. GMT), __TZ should be set to
  32      (timezone_t) 0.
  33
  34    The format string __FORMAT, including GNU extensions, is described in
  35    the GNU libc's strftime() documentation:
  36    <https://www.gnu.org/software/libc/manual/html_node/Formatting-Calendar-Time.html>
  37    Additionally, the following conversion is supported:
  38      %N   The number of nanoseconds, passed as __NS argument.
  39    Here's a summary of the available conversions (= format directives):
  40      literal characters      %n %t %%
  41      date:
  42        century               %C
  43        year                  %Y %y
  44        week-based year       %G %g
  45        month (in year)       %m %B %b %h
  46        week in year          %U %W %V
  47        day in year           %j
  48        day (in month)        %d %e
  49        day in week           %u %w %A %a
  50        year, month, day      %x %F %D
  51      time:
  52        half-day              %p %P
  53        hour                  %H %k %I %l
  54        minute (in hour)      %M
  55        hour, minute          %R
  56        second (in minute)    %S
  57        hour, minute, second  %r %T %X
  58        second (since epoch)  %s
  59      date and time:          %c
  60      time zone:              %z %Z
  61      nanosecond              %N
  62
  63    Stores the result, as a string with a trailing NUL character, at the
  64    beginning of the array __S[0..__MAXSIZE-1], if it fits, and returns
  65    the length of that string, not counting the trailing NUL.  In this case,
  66    errno is preserved if the return value is 0.
  67    If it does not fit, this function sets errno to ERANGE and returns 0.
  68    Upon other errors, this function sets errno and returns 0 as well.
  69
  70    Note: The errno behavior is in draft POSIX 202x plus some requested
  71    changes to POSIX.
  72
  73    This function is like strftime, but with two more arguments:
  74      * __TZ instead of the local timezone information,
  75      * __NS as the number of nanoseconds in the %N directive.
  76  */
  77 size_t nstrftime (char *restrict __s, size_t __maxsize,
  78                   char const *__format,
  79                   struct tm const *__tp, timezone_t __tz, int __ns);
  80
  81 /* Like nstrftime, except that it uses the "C" locale instead of the
  82    current locale.  */
  83 size_t c_nstrftime (char *restrict __s, size_t __maxsize,
  84                     char const *__format,
  85                     struct tm const *__tp, timezone_t __tz, int __ns);
  86
  87 #ifdef __cplusplus
  88 }
  89 #endif