printf.9: document limited conversion specification syntax

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

printf.9: document limited conversion specification syntax

Klemens Nanni-2
print(9) says it only documents differences and points at printf(3) for
identical/shared bits:

   DESCRIPTION
     [...]

     Since each of these kernel functions is a variant of its user space
     counterpart, this page describes only the differences between the user
     space and kernel versions. Refer to printf(3) for functional details.

   FORMAT OPTIONS
     The kernel functions don't support as many formatting specifiers as their
     user space counterparts.  In addition to the floating point formatting
     specifiers, the following integer type specifiers are not supported:

     %hh    Argument of char type.  This format specifier is accepted by the
            kernel but will be handled as %h.

     %j     Argument of intmax_t or uintmax_t type.

     %t     Argument of ptrdiff_t type.

     The kernel functions support some additional formatting specifiers:

     %b     Bit field expansion.  [...]


So reading this, I get the impression that print(3)'s entire conversion
specifications syntax is supported (merely with a few less `conversion'
specifiers):

        %[argno$][flags][width][.precision][size]conversion

but printf(9) supports much fewer specifiers, afaict amounting to

        %[width][size]conversion

That's fine, but code using printf(3) syntax might actually compile
without warnings (like this example did for me) and be useless afterall:

+ printf("%1$s: node %2$x:\n"
+    "  mclk_rate is %3$u (0x%3$x)\n",
+    __func__, sc->sc_node, mclk_rate);

Apr  4 00:32:29 pine64 /bsd:   mclk_rate is   $u (0x  $x)


I don't fancy expanding syntax or adding checks to the kernel's printf.c
but documenting it seems needed.

Feedback? Objections? OK?

diff 5b147494c5d594d5ec97ca57686c9e3527b87e29 /usr/src
blob - c31fb0cb42e9af426c42306a54339ec7f7f375a7
file + share/man/man9/printf.9
--- share/man/man9/printf.9
+++ share/man/man9/printf.9
@@ -119,6 +119,17 @@ send formatted strings to the ddb console, and are onl
 Since each of these kernel functions is a variant of its user space
 counterpart, this page describes only the differences between the user
 space and kernel versions.
+.Pp
+The limited syntax of a conversion specification is:
+.Bd -filled -offset indent
+.Sm off
+.Cm %
+.Op Ar width
+.Op Ar size
+.Ar conversion
+.Sm on
+.Ed
+.Pp
 Refer to
 .Xr printf 3
 for functional details.

Reply | Threaded
Open this post in threaded view
|

Re: printf.9: document limited conversion specification syntax

Jason McIntyre-2
On Sun, Apr 04, 2021 at 01:22:23AM +0200, Klemens Nanni wrote:

> print(9) says it only documents differences and points at printf(3) for
> identical/shared bits:
>
>    DESCRIPTION
>      [...]
>
>      Since each of these kernel functions is a variant of its user space
>      counterpart, this page describes only the differences between the user
>      space and kernel versions. Refer to printf(3) for functional details.
>
>    FORMAT OPTIONS
>      The kernel functions don't support as many formatting specifiers as their
>      user space counterparts.  In addition to the floating point formatting
>      specifiers, the following integer type specifiers are not supported:
>
>      %hh    Argument of char type.  This format specifier is accepted by the
>             kernel but will be handled as %h.
>
>      %j     Argument of intmax_t or uintmax_t type.
>
>      %t     Argument of ptrdiff_t type.
>
>      The kernel functions support some additional formatting specifiers:
>
>      %b     Bit field expansion.  [...]
>
>
> So reading this, I get the impression that print(3)'s entire conversion
> specifications syntax is supported (merely with a few less `conversion'
> specifiers):
>
> %[argno$][flags][width][.precision][size]conversion
>
> but printf(9) supports much fewer specifiers, afaict amounting to
>
> %[width][size]conversion
>
> That's fine, but code using printf(3) syntax might actually compile
> without warnings (like this example did for me) and be useless afterall:
>
> + printf("%1$s: node %2$x:\n"
> +    "  mclk_rate is %3$u (0x%3$x)\n",
> +    __func__, sc->sc_node, mclk_rate);
>
> Apr  4 00:32:29 pine64 /bsd:   mclk_rate is   $u (0x  $x)
>
>
> I don't fancy expanding syntax or adding checks to the kernel's printf.c
> but documenting it seems needed.
>
> Feedback? Objections? OK?
>
> diff 5b147494c5d594d5ec97ca57686c9e3527b87e29 /usr/src
> blob - c31fb0cb42e9af426c42306a54339ec7f7f375a7
> file + share/man/man9/printf.9
> --- share/man/man9/printf.9
> +++ share/man/man9/printf.9
> @@ -119,6 +119,17 @@ send formatted strings to the ddb console, and are onl
>  Since each of these kernel functions is a variant of its user space
>  counterpart, this page describes only the differences between the user
>  space and kernel versions.
> +.Pp
> +The limited syntax of a conversion specification is:

hi. i'm fine with your diff, though cannot really judge the actual
content. but the "limited syntax" text is a bit ambiguous. you could
still expect from it that a full syntax version is supported.

maybe spell it out?

        printf(9) supports a subset of the conversion specification
        available to printf(3):

sth like that?
jmc

> +.Bd -filled -offset indent
> +.Sm off
> +.Cm %
> +.Op Ar width
> +.Op Ar size
> +.Ar conversion
> +.Sm on
> +.Ed
> +.Pp
>  Refer to
>  .Xr printf 3
>  for functional details.
>

Reply | Threaded
Open this post in threaded view
|

Re: printf.9: document limited conversion specification syntax

Klemens Nanni-2
On Sun, Apr 04, 2021 at 07:17:27AM +0100, Jason McIntyre wrote:

> On Sun, Apr 04, 2021 at 01:22:23AM +0200, Klemens Nanni wrote:
> > @@ -119,6 +119,17 @@ send formatted strings to the ddb console, and are onl
> >  Since each of these kernel functions is a variant of its user space
> >  counterpart, this page describes only the differences between the user
> >  space and kernel versions.
> > +.Pp
> > +The limited syntax of a conversion specification is:
>
> hi. i'm fine with your diff, though cannot really judge the actual
> content. but the "limited syntax" text is a bit ambiguous. you could
> still expect from it that a full syntax version is supported.
Right, I do imply that nothing more is supported;  this sentence is a
cheap copy of printf(3)'s sentence

     The overall syntax of a conversion specification is:

> maybe spell it out?
>
> printf(9) supports a subset of the conversion specification
> available to printf(3):
>
> sth like that?
Thanks, how about this?

     Only a subset of the user space conversion specification is available to
     the kernel version:

           %[width][size]conversion

     Refer to printf(3) for functional details.



Index: share/man/man9/printf.9
===================================================================
RCS file: /cvs/src/share/man/man9/printf.9,v
retrieving revision 1.24
diff -u -p -r1.24 printf.9
--- share/man/man9/printf.9 7 Nov 2015 03:48:25 -0000 1.24
+++ share/man/man9/printf.9 4 Apr 2021 13:39:02 -0000
@@ -119,6 +119,18 @@ send formatted strings to the ddb consol
 Since each of these kernel functions is a variant of its user space
 counterpart, this page describes only the differences between the user
 space and kernel versions.
+.Pp
+Only a subset of the user space conversion specification is available to the
+kernel version:
+.Bd -filled -offset indent
+.Sm off
+.Cm %
+.Op Ar width
+.Op Ar size
+.Ar conversion
+.Sm on
+.Ed
+.Pp
 Refer to
 .Xr printf 3
 for functional details.

Reply | Threaded
Open this post in threaded view
|

Re: printf.9: document limited conversion specification syntax

Jason McIntyre-2
yep, better than mine. ok
jmc

On 4 April 2021 14:41:13 BST, Klemens Nanni <[hidden email]> wrote:

>On Sun, Apr 04, 2021 at 07:17:27AM +0100, Jason McIntyre wrote:
>> On Sun, Apr 04, 2021 at 01:22:23AM +0200, Klemens Nanni wrote:
>> > @@ -119,6 +119,17 @@ send formatted strings to the ddb console, and
>are onl
>> >  Since each of these kernel functions is a variant of its user
>space
>> >  counterpart, this page describes only the differences between the
>user
>> >  space and kernel versions.
>> > +.Pp
>> > +The limited syntax of a conversion specification is:
>>
>> hi. i'm fine with your diff, though cannot really judge the actual
>> content. but the "limited syntax" text is a bit ambiguous. you could
>> still expect from it that a full syntax version is supported.
>Right, I do imply that nothing more is supported;  this sentence is a
>cheap copy of printf(3)'s sentence
>
>     The overall syntax of a conversion specification is:
>
>> maybe spell it out?
>>
>> printf(9) supports a subset of the conversion specification
>> available to printf(3):
>>
>> sth like that?
>Thanks, how about this?
>
>Only a subset of the user space conversion specification is available
>to
>     the kernel version:
>
>           %[width][size]conversion
>
>     Refer to printf(3) for functional details.
>
>
>
>Index: share/man/man9/printf.9
>===================================================================
>RCS file: /cvs/src/share/man/man9/printf.9,v
>retrieving revision 1.24
>diff -u -p -r1.24 printf.9
>--- share/man/man9/printf.9 7 Nov 2015 03:48:25 -0000 1.24
>+++ share/man/man9/printf.9 4 Apr 2021 13:39:02 -0000
>@@ -119,6 +119,18 @@ send formatted strings to the ddb consol
> Since each of these kernel functions is a variant of its user space
> counterpart, this page describes only the differences between the user
> space and kernel versions.
>+.Pp
>+Only a subset of the user space conversion specification is available
>to the
>+kernel version:
>+.Bd -filled -offset indent
>+.Sm off
>+.Cm %
>+.Op Ar width
>+.Op Ar size
>+.Ar conversion
>+.Sm on
>+.Ed
>+.Pp
> Refer to
> .Xr printf 3
> for functional details.

Reply | Threaded
Open this post in threaded view
|

Re: printf.9: document limited conversion specification syntax

Theo de Raadt-2
Yep, all good


Jason McIntyre <[hidden email]> wrote:

> yep, better than mine. ok
> jmc
>
> On 4 April 2021 14:41:13 BST, Klemens Nanni <[hidden email]> wrote:
> >On Sun, Apr 04, 2021 at 07:17:27AM +0100, Jason McIntyre wrote:
> >> On Sun, Apr 04, 2021 at 01:22:23AM +0200, Klemens Nanni wrote:
> >> > @@ -119,6 +119,17 @@ send formatted strings to the ddb console, and
> >are onl
> >> >  Since each of these kernel functions is a variant of its user
> >space
> >> >  counterpart, this page describes only the differences between the
> >user
> >> >  space and kernel versions.
> >> > +.Pp
> >> > +The limited syntax of a conversion specification is:
> >>
> >> hi. i'm fine with your diff, though cannot really judge the actual
> >> content. but the "limited syntax" text is a bit ambiguous. you could
> >> still expect from it that a full syntax version is supported.
> >Right, I do imply that nothing more is supported;  this sentence is a
> >cheap copy of printf(3)'s sentence
> >
> >     The overall syntax of a conversion specification is:
> >
> >> maybe spell it out?
> >>
> >> printf(9) supports a subset of the conversion specification
> >> available to printf(3):
> >>
> >> sth like that?
> >Thanks, how about this?
> >
> >Only a subset of the user space conversion specification is available
> >to
> >     the kernel version:
> >
> >           %[width][size]conversion
> >
> >     Refer to printf(3) for functional details.
> >
> >
> >
> >Index: share/man/man9/printf.9
> >===================================================================
> >RCS file: /cvs/src/share/man/man9/printf.9,v
> >retrieving revision 1.24
> >diff -u -p -r1.24 printf.9
> >--- share/man/man9/printf.9 7 Nov 2015 03:48:25 -0000 1.24
> >+++ share/man/man9/printf.9 4 Apr 2021 13:39:02 -0000
> >@@ -119,6 +119,18 @@ send formatted strings to the ddb consol
> > Since each of these kernel functions is a variant of its user space
> > counterpart, this page describes only the differences between the user
> > space and kernel versions.
> >+.Pp
> >+Only a subset of the user space conversion specification is available
> >to the
> >+kernel version:
> >+.Bd -filled -offset indent
> >+.Sm off
> >+.Cm %
> >+.Op Ar width
> >+.Op Ar size
> >+.Ar conversion
> >+.Sm on
> >+.Ed
> >+.Pp
> > Refer to
> > .Xr printf 3
> > for functional details.
>