diff options
Diffstat (limited to 'static/netbsd/man3/strftime.3')
| -rw-r--r-- | static/netbsd/man3/strftime.3 | 545 |
1 files changed, 545 insertions, 0 deletions
diff --git a/static/netbsd/man3/strftime.3 b/static/netbsd/man3/strftime.3 new file mode 100644 index 00000000..b800a7fd --- /dev/null +++ b/static/netbsd/man3/strftime.3 @@ -0,0 +1,545 @@ +.\" Copyright (c) 1989, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)strftime.3 5.12 (Berkeley) 6/29/91 +.\" $NetBSD: strftime.3,v 1.41 2025/04/08 21:28:48 riastradh Exp $ +.\" +.Dd April 6, 2025 +.Dt STRFTIME 3 +.Os +.Sh NAME +.Nm strftime +.Nd format date and time +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft size_t +.Fo strftime +.Fa "char * restrict buf" +.Fa "size_t maxsize" +.Fa "const char * restrict format" +.Fa "const struct tm * restrict timeptr" +.Fc +.Ft size_t +.Fo strftime_l +.Fa "char * restrict buf" +.Fa "size_t maxsize" +.Fa "const char * restrict format" +.Fa "const struct tm * restrict timeptr" +.Fa "locale_t loc" +.Fc +.Ft size_t +.Fo strftime_z +.Fa "const timezone_t tz" +.Fa "char * restrict buf" +.Fa "size_t maxsize" +.Fa "const char * restrict format" +.Fa "const struct tm * restrict timeptr" +.Fc +.Ft size_t +.Fo strftime_lz +.Fa "const timezone_t tz" +.Fa "char * restrict buf" +.Fa "size_t maxsize" +.Fa "const char * restrict format" +.Fa "const struct tm * restrict timeptr" +.Fa "locale_t loc" +.Fc +.Sh DESCRIPTION +The +.Fn strftime +function formats the information from +.Fa timeptr +into the array pointed to by +.Fa buf +according to the string pointed to by +.Fa format . +.Pp +The function +.Fn strftime_l +does the same as +.Fn strftime +but takes an explicit locale specified in the +.Ft "locale_t" +.Fa loc +argument, rather than using the current locale. +.Pp +The function +.Fn strftime_z +is similar to +.Fn strftime , +but uses an explicit timezone specified in the +.Ft "const timezone_t" +.Fa tz +argument, instead of using the default from the environment. +.Pp +The function +.Fn strftime_lz +does the same as +.Fn strftime +but takes both an explicit timezone and locale arguments. +.Pp +The +.Fa format +string consists of zero or more conversion specifications and +ordinary characters. +All ordinary characters are copied directly into the array. +A conversion specification consists of a percent sign +.Ql % +and one other character. +.Pp +No more than +.Fa maxsize +characters will be placed into the array. +If the total number of resulting characters, including the terminating +NUL character, is not more than +.Fa maxsize , +.Fn strftime +returns the number of characters in the array, not counting the +terminating NUL. +Otherwise, zero is returned and the buffer contents are indeterminate. +.Pp +Each conversion specification is replaced by the characters as +follows which are then copied into the array. +The characters depend on the values of zero or more members of +.Fa timeptr +as specified by brackets in the description. +If a bracketed member name is followed by +.Dq + , +.Nm strftime +can use the named member even though POSIX.1-2024 does not list it; +if the name is followed by +.Dq \&- , +.Nm strftime +ignores the member even though POSIX.1-2024 lists it +which means portable code should set it. +For portability, +.Fa timeptr +should be initialized as if by a successful call to +.Xr gmtime 3 , +.Xr localtime 3 , +.Xr mktime 3 , +.Xr timegm 3 , +or similar functions. +.Bl -tag -width "xxxx" +.It Cm \&%A +is replaced by the locale's full weekday name. +.Dv [ tm_wday ] +.It Cm %a +is replaced by the locale's abbreviated weekday name. +.Dv [ tm_wday ] +.It Cm \&%B +is replaced by the locale's full month name. +.Dv [ tm_mon ] +.It Cm \&%b No or Cm \&%h +is replaced by the locale's abbreviated month name. +.RI [ tm_mon ] +.It Cm \&%C +is replaced by the century (a year divided by 100 and truncated to an integer) +as a decimal number, with at least two digits by default. +.RI [ tm_year ] +.It Cm \&%c +is replaced by the locale's appropriate date and time representation. +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_mon , +.Dv tm_mday , +.Dv tm_wday , +.Dv tm_hour , +.Dv tm_min , +.Dv tm_sec , +.Dv tm_gmtoff , +.Dv tm_zone , +.Dv tm_isdst \&-]. +.It Cm \&%D +is replaced by the date in the format +.Dq Li %m/%d/%y . +Although used in the United States for current dates, +this format is ambiguous elsewhere +and for dates that might involve other centuries. +.Dv [ tm_year , +.Dv tm_mon , +.Dv tm_mday ] +.It Cm \&%d +is replaced by the day of the month as a decimal number [01,31]. +.Dv [ tm_mday ] +.It Cm %d +is replaced by the day of the month as a decimal number (01-31). +.It Cm %E* %O* +POSIX locale extensions. +The sequences +%Ec %EC %Ex %EX %Ey %EY +%Od %Oe %OH %OI %Om %OM +%OS %Ou %OU %OV %Ow %OW %Oy +are supposed to provide alternate +representations. +.Pp +Additionally %OB implemented +to represent alternative months names +(used standalone, without day mentioned). +.It Cm \&%e +is replaced by the day of month as a decimal number [1,31]; +single digits are preceded by a blank. +.Dv [ tm_mday ] +.It Cm \&%F +is equivalent to +.Dq Li %Y-%m-%d +(the ISO 8601 date format). +.Dv [ tm_year , +.Dv tm_mon , +.Dv tm_mday ] +.It Cm \&%G +is replaced by the ISO 8601 year with century as a decimal number. +See also the +.Cm \&%V +conversion specification +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_wday ] +.It Cm \&%g +is replaced by the ISO 8601 year without century as a decimal number. +This is the year that includes the greater part of the week. +(Monday as the first day of a week). +See also the +.Ql \&%V +conversion specification. +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_wday ] +.It Cm \&%H +is replaced by the hour (24-hour clock) as a decimal number [00,23]. +.Dv [ tm_hour ] +.It Cm \&%I +is replaced by the hour (12-hour clock) as a decimal number [01,12]. +.Dv [ tm_hour ] +.It Cm \&%j +is replaced by the day of the year as a decimal number [001,366]. +.Dv [ tm_yday ] +.It Cm \&%k +is replaced by the hour (24-hour clock) as a decimal number [0,23]; +single digits are preceded by a blank. +.Dv [ tm_hour ] +.It Cm \&%l +is replaced by the hour (12-hour clock) as a decimal number [1,12]; +single digits are preceded by a blank. +.Dv [ tm_hour ] +.It Cm \&%M +is replaced by the minute as a decimal number [00,59]. +.Dv [ tm_min ] +.It Cm %m +is replaced by the month as a decimal number [01,12]. +.Dv [ tm_mon ] +.It Cm %n +is replaced by a newline. +.It Cm %p +is replaced by the locale's equivalent of either +.Dq Tn AM +or +.Dq Tn PM . +.Dv [ tm_hour ] +.It Cm \&%R +is replaced by the time in the format +.Dq Li %H:%M . +.Dv [ tm_hour , +.Dv tm_min ] +.It Cm \&%r +is replaced by the locale's representation of 12-hour clock time +using AM/PM notation. +.It Cm \&%S +is replaced by the second as a decimal number [00,60]. +The range of +seconds is [00-60] instead of [00-59] to allow for the periodic occurrence +of leap seconds. +.Dv [ tm_sec ] +.It Cm \&%s +is replaced by the number of seconds since the Epoch (see +.Xr ctime 3 ) . +Although %s is reliable in this implementation, +it can have glitches on other platforms +(notably obsolescent platforms lacking +.Fa tm_gmtoff +or where +.Tp time_t +is no wider than int), and POSIX allows +.Nm strftime +to set +.Dv errno +to +.Dv EINVAL +or +.Dv EOVERFLOW +and return 0 if the number of seconds would be negative or out of range for +.Tp time_t . +Portable code should therefore format a +.Tp time_t +value directly via something like +.Xr snprintf 3 +instead of via +.Xr localtime 3 +followed by +.Nm strftime +with "%s". +.Dv [ tm_year , +.Dv tm_mon , +.Dv tm_mday , +.Dv tm_hour , +.Dv tm_min , +.Dv tm_sec , +.Dv tm_gmtoff +, +.Dv tm_isdst \&-]. +.It Cm \&%T +is replaced by the time in the format +.Dq Li %H:%M:%S . +.Dv [ tm_hour , +.Dv tm_min , +.Dv tm_sec ] +.It Cm \&%t +is replaced by a tab. +.It Cm \&%U +is replaced by the week number of the year (Sunday as the first day of +the week) as a decimal number [00,53]. +.Dv [ tm_wday , +.Dv tm_yday , +.Dv tm_year \&-] +.It Cm \&%u +is replaced by the weekday (Monday as the first day of the week) +as a decimal number [1,7]. +.Dv [ tm_wday ] +.It Cm \&%V +is replaced by the week number of the year (Monday as the first day of +the week) as a decimal number [01,53]. According to ISO 8601 the week +containing January 1 is week 1 if it has four or more days in the new year, +otherwise it is week 53 of the previous year, and the next week is week 1. +The year is given by the +.Ql \&%G +conversion specification. +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_wday ] +.It Cm \&%v +is replaced by the date in the format +.Dq Li %e-%b-%Y . +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_wday ] +.It Cm \&%W +is replaced by the week number of the year (Monday as the first day of +the week) as a decimal number [00,53]. +.Dv [ tm_yday , +.Dv tm_wday ] +.It Cm \&%w +is replaced by the weekday (Sunday as the first day of the week) +as a decimal number [0,6]. +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_wday ] +.It Cm \&%X +is replaced by the locale's appropriate time representation. +.Dv [ tm_year \&-, +.Dv tm_yday \&-, +.Dv tm_mon \&-, +.Dv tm_mday \&-, +.Dv tm_wday \&-, +.Dv tm_hour , +.Dv tm_min , +.Dv tm_sec , +.Dv tm_gmtoff , +.Dv tm_zone , +.Dv tm_isdst \&-]. +.It Cm \&%x +is replaced by the locale's appropriate date representation. +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_mon , +.Dv tm_mday , +.Dv tm_wday , +.Dv tm_hour \&-, +.Dv tm_min \&-, +.Dv tm_sec \&-, +.Dv tm_gmtoff \&-, +.Dv tm_zone \&-, +.Dv tm_isdst \&-]. +.It Cm \&%Y +is replaced by the year with century as a decimal number. +.Dv [ tm_year ] +.It Cm \&%y +is replaced by the year without century as a decimal number [00,99]. +.Dv [ tm_year ] +.It Cm \&%Z +is replaced by the time zone abbreviation, +or the empty string if this is not determinable. +.Dv [ tm_zone , +.Dv tm_isdst \&-] +.It Cm \&%z +is replaced by the offset from the Prime Meridian in the format ++HHMM or -HHMM (ISO 8601) as appropriate, with positive values representing +locations east of Greenwich, or by the empty string if this is +not determinable. +The numeric time zone abbreviation \&-0000 is used when the time is +Universal Time +but local time is indeterminate; by convention this is used for +locations while uninhabited, and corresponds to a zero offset when the +time zone abbreviation begins with +.Dq Li [-] . +.It Cm %+ +is replaced by locale's date and time in +.Xr date 1 +format. +On +.Nx +currently this only works for the C locale. +.Dv [ tm_year , +.Dv tm_yday , +.Dv tm_mon , +.Dv tm_mday , +.Dv tm_wday , +.Dv tm_hour , +.Dv tm_min , +.Dv tm_sec , +.Dv tm_gmtoff , +.Dv tm_zone ] +.It Cm %-* +GNU libc extension. +Do not do any padding when performing numerical outputs. +.It Cm %_* +GNU libc extension. +Explicitly specify space for padding. +.It Cm %0* +GNU libc extension. +Explicitly specify zero for padding. +.It Cm %% +is replaced by as single +.Ql % . +.El +.Pp +As a side effect, +.Nm strftime +also behaves as if +.Xr tzset 3 +were called. +This is for compatibility with older platforms, as required by POSIX; +it is not needed for +.Nm strftime +'s +own use. +.Sh RETURN VALUES +If the conversion is successful, +.Nm +returns the number of bytes placed into the array, not counting the +terminating +.Dv NUL ; +.Va errno +is unchanged if the returned value is zero. +Otherwise, +.Va errno +is set to indicate the error, zero is returned, +and the array contents are unspecified. +.Sh ERRORS +This function fails if: +.Bl -tag -width Er +.It Bq Er ERANGE +The specified file offset is invalid. +The total number of resulting bytes, including the terminating +.Dv NUL +character, is more than +.Fa maxsize . +.It Bq Er EOVERFLOW +The format includes an +.Cm \&%s +conversion and the number of seconds since the Epoch cannot be represented +in a +.Ft time_t . +.El +.Sh SEE ALSO +.Xr date 1 , +.Xr printf 1 , +.Xr ctime 3 , +.Xr printf 3 , +.Xr strptime 3 , +.Xr tm 3 +.Sh STANDARDS +The +.Fn strftime +function +conforms to +.St -isoC-99 . +The +.Ql \&%C , +.Ql \&%D , +.Ql \&%e , +.Ql \&%g , +.Ql \&%G , +.Ql \&%h , +.Ql \&%k , +.Ql \&%l , +.Ql \&%n , +.Ql \&%r , +.Ql \&%R , +.Ql \&%s , +.Ql \&%t , +.Ql \&%T , +.Ql \&%u , +.Ql \&%V , +and +.Ql \&%v +conversion specifications are extensions. +.Pp +Use of the ISO 8601 conversions may produce non-intuitive results. +Week 01 of a year is per definition the first week which has the Thursday +in this year, which is equivalent to the week which contains the fourth +day of January. +In other words, the first week of a new year is the week which has the +majority of its days in the new year. +Week 01 might also contain days from the previous year and the week +before week 01 of a year is the last week (52 or 53) of the previous +year even if it contains days from the new year. +A week starts with Monday (day 1) and ends with Sunday (day 7). +For example, the first week of the year 1997 lasts from +1996-12-30 to 1997-01-05. +.Sh BUGS +There is no conversion specification for the phase of the moon. +.Pp +The +.Fn strftime +function does not correctly handle multibyte characters in the +.Fa format +argument. +.Pp +A return value of zero does not necessarily indicate an error. +If the resulting string is an empty string, the result value is +zero and it is not possible to distinguish between success and error. +For example, in many locales +.Cm \&%p +yields an empty string. +This problem can be avoided by inserting an extra space at the +beginning of the format string and then skipping over it or removing +it from the result. |