[PATCH] strftime.3: mention strftime_l() with .so link

[PATCH] strftime.3: mention strftime_l() with .so link

[наб]

[-- Attachment #1: Type: text/plain, Size: 2335 bytes --]

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/strftime.3   | 27 ++++++++++++++++++++++++++-
 man3/strftime_l.3 |  1 +
 2 files changed, 27 insertions(+), 1 deletion(-)
 create mode 100644 man3/strftime_l.3

diff --git a/man3/strftime.3 b/man3/strftime.3
index dc98a5122..11da7e787 100644
--- a/man3/strftime.3
+++ b/man3/strftime.3
@@ -27,6 +27,11 @@ Standard C library
 .BI "size_t strftime(char *restrict " s ", size_t " max ,
 .BI "                const char *restrict " format ,
 .BI "                const struct tm *restrict " tm );
+.PP
+.BI "size_t strftime_l(char *restrict " s ", size_t " max ,
+.BI "                  const char *restrict " format ,
+.BI "                  const struct tm *restrict " tm ,
+.BI "                  locale_t " locale );
 .fi
 .SH DESCRIPTION
 The
@@ -471,6 +476,20 @@ as an argument to a
 One example of such alternative forms is the Japanese era calendar scheme in the
 .B ja_JP
 glibc locale.
+.PP
+.\" POSIX.1-2008 TC2:
+.\"   [CX] The strftime_l() function shall be equivalent to the strftime() function, except that the locale data used is from the locale represented by locale.
+.\"   [CX] The behavior is undefined if the locale argument to strftime_l() is the special locale object LC_GLOBAL_LOCALE or is not a valid locale object handle.
+.BR strftime_l ()
+is equivalent to
+.BR strftime (),
+except it uses the specified
+.I locale
+instead of the current locale.
+The behaviour is undefined if
+.I locale
+is invalid or
+.BR LC_GLOBAL_LOCALE .
 .SH RETURN VALUE
 Provided that the result string,
 including the terminating null byte, does not exceed
@@ -516,14 +535,20 @@ lbx lb lb
 l l l.
 Interface	Attribute	Value
 T{
-.BR strftime ()
+.BR strftime (),
+.BR strftime_l ()
 T}	Thread safety	MT-Safe env locale
 .TE
 .hy
 .ad
 .sp 1
 .SH CONFORMING TO
+.BR strftime ():
 SVr4, C89, C99.
+.br
+.BR strftime_l ():
+POSIX.1-2008.
+.PP
 .\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the details
 .\" in the standards changed across versions. Investigate and
 .\" write up.
diff --git a/man3/strftime_l.3 b/man3/strftime_l.3
new file mode 100644
index 000000000..a3aa4b41c
--- /dev/null
+++ b/man3/strftime_l.3
@@ -0,0 +1 @@
+.so man3/strftime.3
-- 
2.30.2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] strftime.3: mention strftime_l() with .so link

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2151 bytes --]

 > mention strftime_l() with .so link

Mention? really?

That's the most downplaying word for describing the addition of full 
documentation for a function. xD

Also, please add the link page name to the list of affecteed pages:
strftime.3, strftime_l.3: ...

You can use the $(man_gitstaged) bash function from ./scripts/ to 
produce your git messages.  I typically use it as:

git commit -sm "$(man_gitstaged): Description goes here"

I appended the following to my .bash_aliases:

if [ -f ~/src/linux/man-pages/man-pages/scripts/bash_aliases ]; then
	. ~/src/linux/man-pages/man-pages/scripts/bash_aliases;
fi;


On 7/19/22 20:48, наб wrote:
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> ---
>   man3/strftime.3   | 27 ++++++++++++++++++++++++++-
>   man3/strftime_l.3 |  1 +
>   2 files changed, 27 insertions(+), 1 deletion(-)
>   create mode 100644 man3/strftime_l.3
> 
> diff --git a/man3/strftime.3 b/man3/strftime.3
> index dc98a5122..11da7e787 100644
> --- a/man3/strftime.3
> +++ b/man3/strftime.3
[...]
> @@ -516,14 +535,20 @@ lbx lb lb
>   l l l.
>   Interface	Attribute	Value
>   T{
> -.BR strftime ()
> +.BR strftime (),
> +.BR strftime_l ()
>   T}	Thread safety	MT-Safe env locale
>   .TE
>   .hy
>   .ad
>   .sp 1
>   .SH CONFORMING TO
> +.BR strftime ():
>   SVr4, C89, C99.
> +.br

Prefer .PP

We avoid raw roff requests in man(7) pages as much as possible.
I'd tell you how to get the same behavior with rare man(7) macros, but I 
don't think we need to complicate it, when .PP is also nice here.
But just for you to know, there's .PD 0 in man(7).


Cheers,

Alex

> +.BR strftime_l ():
> +POSIX.1-2008.
> +.PP
>   .\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the details
>   .\" in the standards changed across versions. Investigate and
>   .\" write up.
> diff --git a/man3/strftime_l.3 b/man3/strftime_l.3
> new file mode 100644
> index 000000000..a3aa4b41c
> --- /dev/null
> +++ b/man3/strftime_l.3
> @@ -0,0 +1 @@
> +.so man3/strftime.3

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] strftime.3: mention strftime_l() with .so link

[наб]

[-- Attachment #1: Type: text/plain, Size: 3107 bytes --]

On Tue, Jul 19, 2022 at 10:50:06PM +0200, Alejandro Colomar wrote:
> Also, please add the link page name to the list of affecteed pages:
> strftime.3, strftime_l.3: ...

Fixed.

> Prefer .PP
> 
> We avoid raw roff requests in man(7) pages as much as possible.
> I'd tell you how to get the same behavior with rare man(7) macros, but I
> don't think we need to complicate it, when .PP is also nice here.
> But just for you to know, there's .PD 0 in man(7).

I grepped for .br specifically and saw it's used so I used it.
Replaced with .PD 0, .PP, .PD to the same effect.

See updated scissor-patch below:
-- >8 --
Date: Tue, 19 Jul 2022 20:46:49 +0200
Subject: [PATCH v2] strftime.3, strftime_l.3: mention strftime_l() with .so
 link

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/strftime.3   | 29 ++++++++++++++++++++++++++++-
 man3/strftime_l.3 |  1 +
 2 files changed, 29 insertions(+), 1 deletion(-)
 create mode 100644 man3/strftime_l.3

diff --git a/man3/strftime.3 b/man3/strftime.3
index dc98a5122..a93c0f4c2 100644
--- a/man3/strftime.3
+++ b/man3/strftime.3
@@ -27,6 +27,11 @@ Standard C library
 .BI "size_t strftime(char *restrict " s ", size_t " max ,
 .BI "                const char *restrict " format ,
 .BI "                const struct tm *restrict " tm );
+.PP
+.BI "size_t strftime_l(char *restrict " s ", size_t " max ,
+.BI "                  const char *restrict " format ,
+.BI "                  const struct tm *restrict " tm ,
+.BI "                  locale_t " locale );
 .fi
 .SH DESCRIPTION
 The
@@ -471,6 +476,20 @@ as an argument to a
 One example of such alternative forms is the Japanese era calendar scheme in the
 .B ja_JP
 glibc locale.
+.PP
+.\" POSIX.1-2008 TC2:
+.\"   [CX] The strftime_l() function shall be equivalent to the strftime() function, except that the locale data used is from the locale represented by locale.
+.\"   [CX] The behavior is undefined if the locale argument to strftime_l() is the special locale object LC_GLOBAL_LOCALE or is not a valid locale object handle.
+.BR strftime_l ()
+is equivalent to
+.BR strftime (),
+except it uses the specified
+.I locale
+instead of the current locale.
+The behaviour is undefined if
+.I locale
+is invalid or
+.BR LC_GLOBAL_LOCALE .
 .SH RETURN VALUE
 Provided that the result string,
 including the terminating null byte, does not exceed
@@ -516,14 +535,22 @@ lbx lb lb
 l l l.
 Interface	Attribute	Value
 T{
-.BR strftime ()
+.BR strftime (),
+.BR strftime_l ()
 T}	Thread safety	MT-Safe env locale
 .TE
 .hy
 .ad
 .sp 1
 .SH CONFORMING TO
+.BR strftime ():
 SVr4, C89, C99.
+.PD 0
+.PP
+.PD
+.BR strftime_l ():
+POSIX.1-2008.
+.PP
 .\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the details
 .\" in the standards changed across versions. Investigate and
 .\" write up.
diff --git a/man3/strftime_l.3 b/man3/strftime_l.3
new file mode 100644
index 000000000..02e797a23
--- /dev/null
+++ b/man3/strftime_l.3
@@ -0,0 +1 @@
+.so man3/strftime.3
-- 
2.30.2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] strftime.3: mention strftime_l() with .so link

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4107 bytes --]

Hi!

On 7/19/22 23:27, наб wrote:
> On Tue, Jul 19, 2022 at 10:50:06PM +0200, Alejandro Colomar wrote:
>> Also, please add the link page name to the list of affecteed pages:
>> strftime.3, strftime_l.3: ...
> 
> Fixed.
> 
>> Prefer .PP
>>
>> We avoid raw roff requests in man(7) pages as much as possible.
>> I'd tell you how to get the same behavior with rare man(7) macros, but I
>> don't think we need to complicate it, when .PP is also nice here.
>> But just for you to know, there's .PD 0 in man(7).
> 
> I grepped for .br specifically and saw it's used so I used it.
> Replaced with .PD 0, .PP, .PD to the same effect.

Yeah, mtk wasn't very happy with me fixing existing pages, under the 
fear of churn.  I'm more concerned with the maintainability issues of 
having existing undesirable code (even if it Just Works for now and 
isn't really broken), since it leads to contributors like you to think 
that we actually use it, and then we (I?) keep receiving patches with 
undesirable code; then I need to have discussions explaining that we 
have old code that uses it, but I'd prefer to avoid it in new code, etc.

So yes, we have old code that at some point I'd like to fix, and I will, 
but there's too much of it. :)

> 
> See updated scissor-patch below:
> -- >8 --
> Date: Tue, 19 Jul 2022 20:46:49 +0200
> Subject: [PATCH v2] strftime.3, strftime_l.3: mention strftime_l() with .so
>   link

Okay, so you want to keep "mention".  I will keep it ;)

Cheers,

Alex

> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> ---
>   man3/strftime.3   | 29 ++++++++++++++++++++++++++++-
>   man3/strftime_l.3 |  1 +
>   2 files changed, 29 insertions(+), 1 deletion(-)
>   create mode 100644 man3/strftime_l.3
> 
> diff --git a/man3/strftime.3 b/man3/strftime.3
> index dc98a5122..a93c0f4c2 100644
> --- a/man3/strftime.3
> +++ b/man3/strftime.3
> @@ -27,6 +27,11 @@ Standard C library
>   .BI "size_t strftime(char *restrict " s ", size_t " max ,
>   .BI "                const char *restrict " format ,
>   .BI "                const struct tm *restrict " tm );
> +.PP
> +.BI "size_t strftime_l(char *restrict " s ", size_t " max ,
> +.BI "                  const char *restrict " format ,
> +.BI "                  const struct tm *restrict " tm ,
> +.BI "                  locale_t " locale );
>   .fi
>   .SH DESCRIPTION
>   The
> @@ -471,6 +476,20 @@ as an argument to a
>   One example of such alternative forms is the Japanese era calendar scheme in the
>   .B ja_JP
>   glibc locale.
> +.PP
> +.\" POSIX.1-2008 TC2:
> +.\"   [CX] The strftime_l() function shall be equivalent to the strftime() function, except that the locale data used is from the locale represented by locale.
> +.\"   [CX] The behavior is undefined if the locale argument to strftime_l() is the special locale object LC_GLOBAL_LOCALE or is not a valid locale object handle.
> +.BR strftime_l ()
> +is equivalent to
> +.BR strftime (),
> +except it uses the specified
> +.I locale
> +instead of the current locale.
> +The behaviour is undefined if
> +.I locale
> +is invalid or
> +.BR LC_GLOBAL_LOCALE .
>   .SH RETURN VALUE
>   Provided that the result string,
>   including the terminating null byte, does not exceed
> @@ -516,14 +535,22 @@ lbx lb lb
>   l l l.
>   Interface	Attribute	Value
>   T{
> -.BR strftime ()
> +.BR strftime (),
> +.BR strftime_l ()
>   T}	Thread safety	MT-Safe env locale
>   .TE
>   .hy
>   .ad
>   .sp 1
>   .SH CONFORMING TO
> +.BR strftime ():
>   SVr4, C89, C99.
> +.PD 0
> +.PP
> +.PD
> +.BR strftime_l ():
> +POSIX.1-2008.
> +.PP
>   .\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the details
>   .\" in the standards changed across versions. Investigate and
>   .\" write up.
> diff --git a/man3/strftime_l.3 b/man3/strftime_l.3
> new file mode 100644
> index 000000000..02e797a23
> --- /dev/null
> +++ b/man3/strftime_l.3
> @@ -0,0 +1 @@
> +.so man3/strftime.3

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] strftime.3: mention strftime_l() with .so link

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 5012 bytes --]



On 7/19/22 23:55, Alejandro Colomar wrote:
> Hi!
> 
> On 7/19/22 23:27, наб wrote:
>> On Tue, Jul 19, 2022 at 10:50:06PM +0200, Alejandro Colomar wrote:
>>> Also, please add the link page name to the list of affecteed pages:
>>> strftime.3, strftime_l.3: ...
>>
>> Fixed.
>>
>>> Prefer .PP
>>>
>>> We avoid raw roff requests in man(7) pages as much as possible.
>>> I'd tell you how to get the same behavior with rare man(7) macros, but I
>>> don't think we need to complicate it, when .PP is also nice here.
>>> But just for you to know, there's .PD 0 in man(7).
>>
>> I grepped for .br specifically and saw it's used so I used it.
>> Replaced with .PD 0, .PP, .PD to the same effect.
> 
> Yeah, mtk wasn't very happy with me fixing existing pages, under the 
> fear of churn.  I'm more concerned with the maintainability issues of 
> having existing undesirable code (even if it Just Works for now and 
> isn't really broken), since it leads to contributors like you to think 
> that we actually use it, and then we (I?) keep receiving patches with 
> undesirable code; then I need to have discussions explaining that we 
> have old code that uses it, but I'd prefer to avoid it in new code, etc.
> 
> So yes, we have old code that at some point I'd like to fix, and I will, 
> but there's too much of it. :)
> 
>>
>> See updated scissor-patch below:
>> -- >8 --
>> Date: Tue, 19 Jul 2022 20:46:49 +0200
>> Subject: [PATCH v2] strftime.3, strftime_l.3: mention strftime_l() 
>> with .so
>>   link
> 
> Okay, so you want to keep "mention".  I will keep it ;)
> 
> Cheers,
> 
> Alex
> 
>>
>> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
>> ---
>>   man3/strftime.3   | 29 ++++++++++++++++++++++++++++-
>>   man3/strftime_l.3 |  1 +
>>   2 files changed, 29 insertions(+), 1 deletion(-)
>>   create mode 100644 man3/strftime_l.3
>>
>> diff --git a/man3/strftime.3 b/man3/strftime.3
>> index dc98a5122..a93c0f4c2 100644
>> --- a/man3/strftime.3
>> +++ b/man3/strftime.3
>> @@ -27,6 +27,11 @@ Standard C library
>>   .BI "size_t strftime(char *restrict " s ", size_t " max ,
>>   .BI "                const char *restrict " format ,
>>   .BI "                const struct tm *restrict " tm );
>> +.PP
>> +.BI "size_t strftime_l(char *restrict " s ", size_t " max ,
>> +.BI "                  const char *restrict " format ,
>> +.BI "                  const struct tm *restrict " tm ,
>> +.BI "                  locale_t " locale );

Sorry, I just realized now.  Alignment of continuation lines should be 
the same for both functions.

See man-pages(7):
    SYNOPSIS
        Wrap  the  function  prototype(s)  in a .nf/.fi pair to prevent
        filling.

        In general, where more than one function prototype is shown  in
        the  SYNOPSIS,  the prototypes should not be separated by blank
        lines.  However, blank lines (achieved using .PP) may be  added
        in the following cases:

        *  to  separate  long lists of function prototypes into related
           groups (see for example list(3));

        *  in other cases that may improve readability.

        In the SYNOPSIS, a long function prototype may need to be  con‐
        tinued  over  to  the  next line.  The continuation line is in‐
        dented according to the following rules:

        1. If there is a single such prototype that needs to be contin‐
           ued, then align the continuation line so that when the  page
           is rendered on a fixed‐width font device (e.g., on an xterm)
           the continuation line starts just below the start of the ar‐
           gument  list in the line above.  (Exception: the indentation
           may be adjusted if necessary to prevent a very long continu‐
           ation line or a further continuation line where the function
           prototype is very long.)  As an example:

               int tcsetattr(int fd, int optional_actions,
                             const struct termios *termios_p);

        2. But, where multiple functions in the SYNOPSIS  require  con‐
           tinuation  lines,  and  the  function  names  have different
           lengths, then align all continuation lines to start  in  the
           same  column.  This provides a nicer rendering in PDF output
           (because the SYNOPSIS  uses  a  variable  width  font  where
           spaces  render  narrower than most characters).  As an exam‐
           ple:

               int getopt(int argc, char * const argv[],
                          const char *optstring);
               int getopt_long(int argc, char * const argv[],
                          const char *optstring,
                          const struct option *longopts, int *longindex);

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] strftime.3: mention strftime_l() with .so link

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4581 bytes --]



On 7/19/22 23:55, Alejandro Colomar wrote:
> Hi!
> 
> On 7/19/22 23:27, наб wrote:
>> On Tue, Jul 19, 2022 at 10:50:06PM +0200, Alejandro Colomar wrote:
>>> Also, please add the link page name to the list of affecteed pages:
>>> strftime.3, strftime_l.3: ...
>>
>> Fixed.
>>
>>> Prefer .PP
>>>
>>> We avoid raw roff requests in man(7) pages as much as possible.
>>> I'd tell you how to get the same behavior with rare man(7) macros, but I
>>> don't think we need to complicate it, when .PP is also nice here.
>>> But just for you to know, there's .PD 0 in man(7).
>>
>> I grepped for .br specifically and saw it's used so I used it.
>> Replaced with .PD 0, .PP, .PD to the same effect.
> 
> Yeah, mtk wasn't very happy with me fixing existing pages, under the 
> fear of churn.  I'm more concerned with the maintainability issues of 
> having existing undesirable code (even if it Just Works for now and 
> isn't really broken), since it leads to contributors like you to think 
> that we actually use it, and then we (I?) keep receiving patches with 
> undesirable code; then I need to have discussions explaining that we 
> have old code that uses it, but I'd prefer to avoid it in new code, etc.
> 
> So yes, we have old code that at some point I'd like to fix, and I will, 
> but there's too much of it. :)
> 
>>
>> See updated scissor-patch below:
>> -- >8 --
>> Date: Tue, 19 Jul 2022 20:46:49 +0200
>> Subject: [PATCH v2] strftime.3, strftime_l.3: mention strftime_l() 
>> with .so
>>   link
> 
> Okay, so you want to keep "mention".  I will keep it ;)
> 
> Cheers,
> 
> Alex
> 
>>
>> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
>> ---
>>   man3/strftime.3   | 29 ++++++++++++++++++++++++++++-
>>   man3/strftime_l.3 |  1 +
>>   2 files changed, 29 insertions(+), 1 deletion(-)
>>   create mode 100644 man3/strftime_l.3
>>
>> diff --git a/man3/strftime.3 b/man3/strftime.3
>> index dc98a5122..a93c0f4c2 100644
>> --- a/man3/strftime.3
>> +++ b/man3/strftime.3
>> @@ -27,6 +27,11 @@ Standard C library
>>   .BI "size_t strftime(char *restrict " s ", size_t " max ,
>>   .BI "                const char *restrict " format ,
>>   .BI "                const struct tm *restrict " tm );
>> +.PP
>> +.BI "size_t strftime_l(char *restrict " s ", size_t " max ,
>> +.BI "                  const char *restrict " format ,
>> +.BI "                  const struct tm *restrict " tm ,
>> +.BI "                  locale_t " locale );
>>   .fi
>>   .SH DESCRIPTION
>>   The
>> @@ -471,6 +476,20 @@ as an argument to a
>>   One example of such alternative forms is the Japanese era calendar 
>> scheme in the
>>   .B ja_JP
>>   glibc locale.
>> +.PP
>> +.\" POSIX.1-2008 TC2:
>> +.\"   [CX] The strftime_l() function shall be equivalent to the 
>> strftime() function, except that the locale data used is from the 
>> locale represented by locale.
>> +.\"   [CX] The behavior is undefined if the locale argument to 
>> strftime_l() is the special locale object LC_GLOBAL_LOCALE or is not a 
>> valid locale object handle.

Maybe these comments would be better placed in the commit message?  I 
tend to dislike code comments.

>> +.BR strftime_l ()
>> +is equivalent to
>> +.BR strftime (),
>> +except it uses the specified
>> +.I locale
>> +instead of the current locale.
>> +The behaviour is undefined if
>> +.I locale
>> +is invalid or
>> +.BR LC_GLOBAL_LOCALE .
>>   .SH RETURN VALUE
>>   Provided that the result string,
>>   including the terminating null byte, does not exceed
>> @@ -516,14 +535,22 @@ lbx lb lb
>>   l l l.
>>   Interface    Attribute    Value
>>   T{
>> -.BR strftime ()
>> +.BR strftime (),
>> +.BR strftime_l ()
>>   T}    Thread safety    MT-Safe env locale
>>   .TE
>>   .hy
>>   .ad
>>   .sp 1
>>   .SH CONFORMING TO
>> +.BR strftime ():
>>   SVr4, C89, C99.
>> +.PD 0
>> +.PP
>> +.PD
>> +.BR strftime_l ():
>> +POSIX.1-2008.
>> +.PP
>>   .\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the 
>> details
>>   .\" in the standards changed across versions. Investigate and
>>   .\" write up.
>> diff --git a/man3/strftime_l.3 b/man3/strftime_l.3
>> new file mode 100644
>> index 000000000..02e797a23
>> --- /dev/null
>> +++ b/man3/strftime_l.3
>> @@ -0,0 +1 @@
>> +.so man3/strftime.3
> 

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v4] strftime.3, strftime_l.3: mention strftime_l() with .so link

[наб]

[-- Attachment #1: Type: text/plain, Size: 2341 bytes --]

POSIX.1-2008 TC2:
> [CX] The strftime_l() function shall be equivalent to the strftime()
  function, except that the locale data used is from the locale
  represented by locale.
> [CX] The behavior is undefined if the locale argument to strftime_l()
  is the special locale object LC_GLOBAL_LOCALE or is not a valid locale
  object handle.

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/strftime.3   | 26 +++++++++++++++++++++++++-
 man3/strftime_l.3 |  1 +
 2 files changed, 26 insertions(+), 1 deletion(-)
 create mode 100644 man3/strftime_l.3

diff --git a/man3/strftime.3 b/man3/strftime.3
index dc98a5122..6eff815ad 100644
--- a/man3/strftime.3
+++ b/man3/strftime.3
@@ -27,6 +27,11 @@ Standard C library
 .BI "size_t strftime(char *restrict " s ", size_t " max ,
 .BI "                const char *restrict " format ,
 .BI "                const struct tm *restrict " tm );
+.PP
+.BI "size_t strftime_l(char *restrict " s ", size_t " max ,
+.BI "                const char *restrict " format ,
+.BI "                const struct tm *restrict " tm ,
+.BI "                locale_t " locale );
 .fi
 .SH DESCRIPTION
 The
@@ -471,6 +476,17 @@ as an argument to a
 One example of such alternative forms is the Japanese era calendar scheme in the
 .B ja_JP
 glibc locale.
+.PP
+.BR strftime_l ()
+is equivalent to
+.BR strftime (),
+except it uses the specified
+.I locale
+instead of the current locale.
+The behaviour is undefined if
+.I locale
+is invalid or
+.BR LC_GLOBAL_LOCALE .
 .SH RETURN VALUE
 Provided that the result string,
 including the terminating null byte, does not exceed
@@ -516,14 +532,22 @@ lbx lb lb
 l l l.
 Interface	Attribute	Value
 T{
-.BR strftime ()
+.BR strftime (),
+.BR strftime_l ()
 T}	Thread safety	MT-Safe env locale
 .TE
 .hy
 .ad
 .sp 1
 .SH CONFORMING TO
+.BR strftime ():
 SVr4, C89, C99.
+.PD 0
+.PP
+.PD
+.BR strftime_l ():
+POSIX.1-2008.
+.PP
 .\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the details
 .\" in the standards changed across versions. Investigate and
 .\" write up.
diff --git a/man3/strftime_l.3 b/man3/strftime_l.3
new file mode 100644
index 000000000..02e797a23
--- /dev/null
+++ b/man3/strftime_l.3
@@ -0,0 +1 @@
+.so man3/strftime.3
-- 
2.30.2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v4] strftime.3, strftime_l.3: mention strftime_l() with .so link

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2653 bytes --]

On 7/20/22 00:28, наб wrote:
> POSIX.1-2008 TC2:
>> [CX] The strftime_l() function shall be equivalent to the strftime()
>    function, except that the locale data used is from the locale
>    represented by locale.
>> [CX] The behavior is undefined if the locale argument to strftime_l()
>    is the special locale object LC_GLOBAL_LOCALE or is not a valid locale
>    object handle.
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

Patch applied.

Thanks,

Alex

> ---
>   man3/strftime.3   | 26 +++++++++++++++++++++++++-
>   man3/strftime_l.3 |  1 +
>   2 files changed, 26 insertions(+), 1 deletion(-)
>   create mode 100644 man3/strftime_l.3
> 
> diff --git a/man3/strftime.3 b/man3/strftime.3
> index dc98a5122..6eff815ad 100644
> --- a/man3/strftime.3
> +++ b/man3/strftime.3
> @@ -27,6 +27,11 @@ Standard C library
>   .BI "size_t strftime(char *restrict " s ", size_t " max ,
>   .BI "                const char *restrict " format ,
>   .BI "                const struct tm *restrict " tm );
> +.PP
> +.BI "size_t strftime_l(char *restrict " s ", size_t " max ,
> +.BI "                const char *restrict " format ,
> +.BI "                const struct tm *restrict " tm ,
> +.BI "                locale_t " locale );
>   .fi
>   .SH DESCRIPTION
>   The
> @@ -471,6 +476,17 @@ as an argument to a
>   One example of such alternative forms is the Japanese era calendar scheme in the
>   .B ja_JP
>   glibc locale.
> +.PP
> +.BR strftime_l ()
> +is equivalent to
> +.BR strftime (),
> +except it uses the specified
> +.I locale
> +instead of the current locale.
> +The behaviour is undefined if
> +.I locale
> +is invalid or
> +.BR LC_GLOBAL_LOCALE .
>   .SH RETURN VALUE
>   Provided that the result string,
>   including the terminating null byte, does not exceed
> @@ -516,14 +532,22 @@ lbx lb lb
>   l l l.
>   Interface	Attribute	Value
>   T{
> -.BR strftime ()
> +.BR strftime (),
> +.BR strftime_l ()
>   T}	Thread safety	MT-Safe env locale
>   .TE
>   .hy
>   .ad
>   .sp 1
>   .SH CONFORMING TO
> +.BR strftime ():
>   SVr4, C89, C99.
> +.PD 0
> +.PP
> +.PD
> +.BR strftime_l ():
> +POSIX.1-2008.
> +.PP
>   .\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the details
>   .\" in the standards changed across versions. Investigate and
>   .\" write up.
> diff --git a/man3/strftime_l.3 b/man3/strftime_l.3
> new file mode 100644
> index 000000000..02e797a23
> --- /dev/null
> +++ b/man3/strftime_l.3
> @@ -0,0 +1 @@
> +.so man3/strftime.3

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]