--- name: "jstrftime" section: "3" platform: "linux" package: "jcal" version: "0.5.1-0.2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/jstrftime" --- # jstrftime(3) format jalali date and time ## NAME jstrftime - format jalali date and time ## SYNOPSIS ``` #include size_t jstrftime(char *s, size_t max, const char *format, const struct tm *jtm); ``` Link with -ljalali ## DESCRIPTION The **jstrftime**() function formats the broken-down jalali time *jtm* according to the format specification *format* and places the result in the character array *s* of size *max*. The format specification is a null-terminated string and may contain special character sequences called *conversion specifications*, each of which is introduced by a '%' character and terminated by some other character known as a *conversion specifier character*. All other character sequences are *ordinary character sequences*. The characters of ordinary character sequences (including the null byte) are copied verbatim from *format* to *s*. However, the characters of conversion specifications are replaced as follows: - **%a** The abbreviated weekday name. - **%A** The full weekday name. - **%b** The abbreviated month name. - **%B** The full month name. - **%c** The preferred date and time representation. - **%C** The century number (year/100) as a 2-digit integer. - **%d** The day of the month as a decimal number (range 01 to 31). - **%D** Equivalent to **%Y/%m/%d**. - **%e** Like **%d** The day of the month as a decimal number, but a leading zero is replaced by a space. (SU) - **%E** The preferred date and time in Farsi. (utf8) - **%F** Equivalent to **%Y-%m-%d** (similar to the ISO 8601 date format). (C99) - **%h** The abbreviated Farsi transliterated weekday name. - **%q** The full Farsi transliterated weekday name. - **%g** The abbreviated Farsi weekday name. (utf8) - **%G** The full Farsi weekday name. (utf8) - **%v** The abbreviated Farsi month name. (utf8) - **%V** The full Farsi month name. (utf8) - **%H** The hour as a decimal number using a 24-hour clock (range 00 to 23). - **%I** The hour as a decimal number using a 12-hour clock (range 01 to 12). - **%j** The day of the year as a decimal number (range 001 to 366). - **%k** The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. (See also **%H**.) (TZ) - **%l** The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. (See also **%I**.) (TZ) - **%m** The month as a decimal number (range 01 to 12). - **%M** The minute as a decimal number (range 00 to 59). - **%n** A newline character. (SU) - **%O** AM or PM notation for the given time in Farsi equivalent. (utf8) - **%p** Either "AM" or "PM" according to the given time value. Noon is treated as "PM" and midnight as "AM". - **%P** Like **%p** but in lowercase: "am" or "pm" - **%r** The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to **%I:%M:%S %p**. (SU) - **%R** The time in 24-hour notation (**%H:%M**). (SU) For a version including the seconds, see **%T** below. - **%s** The number of seconds since the Epoch, 1970-01-01 (1348-10-11) 00:00:00 +0000 (UTC). (TZ) - **%S** The second as a decimal number (range 00 to 59). - **%t** A tab character. (SU) - **%T** The time in 24-hour notation (**%H:%M:%S**). (SU) - **%u** The day of the week as a decimal, range 1 to 7, Saturday being 1. See also **%w**. (SU) - **%U** The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. - **%w** The day of the week as a decimal, range 0 to 6, Saturday being 0. See also **%u**. - **%W** The preferred date in %Y/%m/%d format and Farsi. (utf8) - **%x** The preferred date representation without the time. - **%X** The preferred time representation without the date in Farsi. (utf8) - **%y** The year as a decimal number without a century (range 00 to 99). - **%Y** The year as a decimal number including the century. - **%z** The *+hhmm* or *-hhmm* numeric timezone (that is, the hour and minute offset from UTC). (SU) - **%Z** The timezone or name or abbreviation. - **%%** A literal '%' character. The broken-down time structure *tm* is defined in *\*. See also [**jctime**(3)](/jctime/3.md). ## RETURN VALUE The **jstrftime**() function returns the number of characters placed in the array *s*, not including the terminating null byte, provided the string, including the terminating null byte, fits. Otherwise, it returns max, and the contents of the array is undefined. ## ENVIRONMENT The environment variables **TZ** and **LC\_TIME** are used. ## CONFORMING TO C99. ## EXAMPLES **RFC 2822-compliant date format** (with an English locale for %a and %b) "%a, %d %b %Y %T %z" **RFC 822-compliant date format** (with an English locale for %a and %b) "%a, %d %b %y %T %z" ### Example Program The program below can be used to experiment with **jstrftime**(). Some examples of the result string produced by the libjalali implementation of **jstrftime**() are as follows: ``` $ ./a.out '%m' Result string is "11" ``` Here's the program source: ``` #include #include #include #include #include int main(int argc, char *argv[]) { char outstr[200]; time_t t; struct tm *tmp; t = time(NULL); tmp = jlocaltime(&t); if (tmp == NULL) { perror("jlocaltime"); exit(EXIT_FAILURE); } if (jstrftime(outstr, sizeof(outstr), argv[1], tmp) == 0) { fprintf(stderr, "jstrftime returned 0"); exit(EXIT_FAILURE); } printf("Result string is \"%s\"\n", outstr); exit(EXIT_SUCCESS); } ``` ## SEE ALSO [**jdate**(1)](/jdate/1.md), [**jcal**(1)](/jcal/1.md), [**time**(2)](/time/2.md), [**jctime**(3)](/jctime/3.md), [**sprintf**(3)](/sprintf/3.md), [**jstrptime**(3)](/jstrptime/3.md) ## COLOPHON This page is part of release 0.2 of the libjalali *man-pages* ## AUTHOR Written by Ashkan Ghassemi. \ ## REPORTING BUGS Report libjalali bugs to \ libjalali home page: \ ## COPYRIGHT Copyright (C) 2011 Ashkan Ghassemi. License LGPLv3+: GNU LGPL version 3 or later \. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.