diff options
Diffstat (limited to 'newstrftime.3.txt')
| -rw-r--r-- | newstrftime.3.txt | 220 |
1 files changed, 120 insertions, 100 deletions
diff --git a/newstrftime.3.txt b/newstrftime.3.txt index ea210a869f4a..37329d91dbc6 100644 --- a/newstrftime.3.txt +++ b/newstrftime.3.txt @@ -1,149 +1,169 @@ -NAME +NEWSTRFTIME(3) Library Functions Manual NEWSTRFTIME(3) - strftime - format date and time +NAME + strftime - format date and time SYNOPSIS - #include <sys/types.h> - #include <time.h> + #include <time.h> - size_t strftime(buf, maxsize, format, timeptr) - char *buf; - size_t maxsize; - const char *format; - const struct tm *timeptr + size_t strftime(char *restrict buf, size_t maxsize, + char const *restrict format, struct tm const *restrict timeptr); - cc ... -ltz + cc ... -ltz DESCRIPTION - The strftime function formats the information from timeptr - into the buffer buf according to the string pointed to by - format. + The strftime function formats the information from timeptr into the + array pointed to by buf according to the string pointed to by format. + + The 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 + and one other character. + + No more than maxsize bytes are placed into the array. + + Each conversion specification is replaced by the characters as follows + which are then copied into the array. + + %A is replaced by the locale's full weekday name. - The format string consists of zero or more conversion - specifications and ordinary characters. All ordinary - characters are copied directly into the buffer. A - conversion specification consists of a percent sign and one - other character. + %a is replaced by the locale's abbreviated weekday name. - No more than maxsize characters are be placed into the - array. If the total number of resulting characters, - including the terminating null character, is not more than - maxsize, strftime returns the number of characters in the - array, not counting the terminating null. Otherwise, zero - is returned. + %B is replaced by the locale's full month name. - Each conversion specification is replaced by the characters - as follows which are then copied into the buffer. + %b or %h + is replaced by the locale's abbreviated month name. - %A is replaced by the locale's full weekday name. + %C is replaced by the century (a year divided by 100 and truncated + to an integer) as a decimal number [00,99]. - %a is replaced by the locale's abbreviated weekday name. + %c is replaced by the locale's appropriate date and time + representation. - %B is replaced by the locale's full month name. + %D is equivalent to %m/%d/%y. - %b or %h - is replaced by the locale's abbreviated month name. + %d is replaced by the day of the month as a decimal number [01,31]. - %C is replaced by the century (a year divided by 100 and - truncated to an integer) as a decimal number (00-99). + %e is replaced by the day of month as a decimal number [1,31]; + single digits are preceded by a blank. - %c is replaced by the locale's appropriate date and time - representation. + %F is equivalent to %Y-%m-%d (the ISO 8601 date format). - %D is replaced by the date in the format %m/%d/%y. + %G is replaced by the ISO 8601 year with century as a decimal + number. See also the %V conversion specification. - %d is replaced by the day of the month as a decimal number - (01-31). + %g is replaced by the ISO 8601 year without century as a decimal + number [00,99]. This is the year that includes the greater part + of the week. (Monday as the first day of a week). See also the + %V conversion specification. - %e is replaced by the day of month as a decimal number - (1-31); single digits are preceded by a blank. - %F is replaced by the date in the format %Y-%m-%d. + %H is replaced by the hour (24-hour clock) as a decimal number + [00,23]. - %G is replaced by the ISO 8601 year with century as a - decimal number. + %I is replaced by the hour (12-hour clock) as a decimal number + [01,12]. - %g is replaced by the ISO 8601 year without century as a - decimal number (00-99). - %H is replaced by the hour (24-hour clock) as a decimal - number (00-23). + %j is replaced by the day of the year as a decimal number + [001,366]. - %I is replaced by the hour (12-hour clock) as a decimal - number (01-12). + %k is replaced by the hour (24-hour clock) as a decimal number + [0,23]; single digits are preceded by a blank. - %j is replaced by the day of the year as a decimal number - (001-366). + %l is replaced by the hour (12-hour clock) as a decimal number + [1,12]; single digits are preceded by a blank. - %k is replaced by the hour (24-hour clock) as a decimal - number (0-23); single digits are preceded by a blank. + %M is replaced by the minute as a decimal number [00,59]. - %l is replaced by the hour (12-hour clock) as a decimal - number (1-12); single digits are preceded by a blank. + %m is replaced by the month as a decimal number [01,12]. - %M is replaced by the minute as a decimal number (00-59). + %n is replaced by a newline. - %m is replaced by the month as a decimal number (01-12). + %p is replaced by the locale's equivalent of either "AM" or "PM". - %n is replaced by a newline. + %R is replaced by the time in the format %H:%M. - %p is replaced by the locale's equivalent of either AM or - PM. + %r is replaced by the locale's representation of 12-hour clock time + using AM/PM notation. - %R is replaced by the time in the format %H:%M. + %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. - %r is replaced by the locale's representation of 12-hour - clock time using AM/PM notation. + %s is replaced by the number of seconds since the Epoch (see + ctime(3)). - %S is replaced by the second as a decimal number (00-60). + %T is replaced by the time in the format %H:%M:%S. - %s is replaced by the number of seconds since the Epoch, - UTC (see mktime(3)). + %t is replaced by a tab. - %T is replaced by the time in the format %H:%M:%S. + %U is replaced by the week number of the year (Sunday as the first + day of the week) as a decimal number [00,53]. - %t is replaced by a tab. + %u is replaced by the weekday (Monday as the first day of the week) + as a decimal number [1,7]. - %U is replaced by the week number of the year (Sunday as - the first day of the week) as a decimal number (00-53). + %V is replaced by the week number of the year (Monday as the first + day of the week) as a decimal number [01,53]. If the week + containing January 1 has four or more days in the new year, then + it is week 1; otherwise it is week 53 of the previous year, and + the next week is week 1. The year is given by the %G conversion + specification. - %u is replaced by the weekday (Monday as the first day of - the week) as a decimal number (1-7). + %W is replaced by the week number of the year (Monday as the first + day of the week) as a decimal number [00,53]. - %V is replaced by the week number of the year (Monday as - the first day of the week) as a decimal number (01-53). - If the week containing January 1 has four or more days - in the new year, then it is week 1; otherwise it is - week 53 of the previous year, and the next week is week - 1. + %w is replaced by the weekday (Sunday as the first day of the week) + as a decimal number [0,6]. - %W is replaced by the week number of the year (Monday as - the first day of the week) as a decimal number (00-53). + %X is replaced by the locale's appropriate time representation. - %w is replaced by the weekday (Sunday as the first day of - the week) as a decimal number (0-6). + %x is replaced by the locale's appropriate date representation. - %X is replaced by the locale's appropriate time - representation. - %x is replaced by the locale's appropriate date - representation. + %Y is replaced by the year with century as a decimal number. - %Y is replaced by the year with century as a decimal - number. + %y is replaced by the year without century as a decimal number + [00,99]. - %y is replaced by the year without century as a decimal - number (00-99). + %Z is replaced by the time zone abbreviation, or by the empty + string if this is not determinable. - %Z is replaced by the time zone name, or by the empty - string if this is not determinable. + %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 "-". - %z is replaced by the offset from UTC in the format +HHMM - or -HHMM as appropriate, with positive values - representing locations east of Greenwich, or by the - empty string if this is not determinable. + %% is replaced by a single %. - %% is replaced by a single %. + %+ is replaced by the locale's date and time in date(1) format. - %+ is replaced by the date and time in date(1) format. +RETURN VALUE + If the conversion is successful, strftime returns the number of bytes + placed into the array, not counting the terminating NUL; errno is + unchanged if the returned value is zero. Otherwise, errno is set to + indicate the error, zero is returned, and the array contents are + unspecified. + +ERRORS + This function fails if: + + [ERANGE] + The total number of resulting bytes, including the terminating + NUL character, is more than maxsize. + + This function may fail if: + + [EOVERFLOW] + The format includes an %s conversion and the number of seconds + since the Epoch cannot be represented in a time_t. SEE ALSO - date(1), getenv(3), newctime(3), newtzset(3), time(2), - tzfile(5) + date(1), getenv(3), newctime(3), newtzset(3), time(2), tzfile(5) + +BUGS + There is no conversion specification for the phase of the moon. + + NEWSTRFTIME(3) |