Issue in man page resolver.3

Issue in man page resolver.3

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    B<…>int datalen, int buflen → B<…int> I<datalen>, B<int> I<buflen>

"B<int res_nmkquery(>int datalen, int buflen;\n"
"B<           res_state >I<statep>B<,>\n"
"B<           int >I<op>B<, const char *>I<dname>B<, int >I<class>B<,>\n"
"B<           int >I<type>B<, const unsigned char >I<data>B<[>I<datalen>B<], int >I<datalen>B<,>\n"
"B<           const unsigned char *>I<newrr>B<,>\n"
"B<           unsigned char >I<buf>B<[>I<buflen>B<], int >I<buflen>B<);>\n"

Re: Issue in man page resolver.3

[Alejandro Colomar]

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

Hi Helge,

On Sun, Aug 24, 2025 at 02:48:32PM +0000, Helge Kreutzmann wrote:
> Without further ado, the following was found:
> 
> Issue:    B<…>int datalen, int buflen → B<…int> I<datalen>, B<int> I<buflen>

That is on purpose; it's a list of forward-declarations of parameters,
not the parameters themselves.  To distinguish them from actual
parameters, they're in Roman.  (Note the semicolon at the end of the
list of forward declarations.)


Have a lovely day!
Alex

> 
> "B<int res_nmkquery(>int datalen, int buflen;\n"
> "B<           res_state >I<statep>B<,>\n"
> "B<           int >I<op>B<, const char *>I<dname>B<, int >I<class>B<,>\n"
> "B<           int >I<type>B<, const unsigned char >I<data>B<[>I<datalen>B<], int >I<datalen>B<,>\n"
> "B<           const unsigned char *>I<newrr>B<,>\n"
> "B<           unsigned char >I<buf>B<[>I<buflen>B<], int >I<buflen>B<);>\n"

-- 
<https://www.alejandro-colomar.es/>

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

Re: Issue in man page resolver.3

[Helge Kreutzmann]

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

Hello Alejandro,
Am Sun, Aug 24, 2025 at 06:05:31PM +0200 schrieb Alejandro Colomar:
> On Sun, Aug 24, 2025 at 02:48:32PM +0000, Helge Kreutzmann wrote:
> > Without further ado, the following was found:
> > 
> > Issue:    B<…>int datalen, int buflen → B<…int> I<datalen>, B<int> I<buflen>
> 
> That is on purpose; it's a list of forward-declarations of parameters,
> not the parameters themselves.  To distinguish them from actual
> parameters, they're in Roman.  (Note the semicolon at the end of the
> list of forward declarations.)

That is quite confusing, at least to me as a translator (not a
programmer). So they are neither the function themselv (which is in
bold) nor variables (which are in italics)? And the type (here "int")
is printed in Roman on purpose, while it would be bold otherwise (see
below, for e.g. "op", the type is in bold).

And in some pages, only a few of these are actually "forward
parameters", while some others are not? (But I trust you - if you say
this is correct, then I simply align).

And: The name, in this example "datalen", comes from somewhere else
("forward")? I'm asking this because I would like to understand the
implications of these "forward parameters" compared to normal
parameters for translations.

(Or do you have a reference, which explains this, than I will gladly
have a look at it).

> Have a lovely day!

You too.

> Alex
> 
> > 
> > "B<int res_nmkquery(>int datalen, int buflen;\n"
> > "B<           res_state >I<statep>B<,>\n"
> > "B<           int >I<op>B<, const char *>I<dname>B<, int >I<class>B<,>\n"
> > "B<           int >I<type>B<, const unsigned char >I<data>B<[>I<datalen>B<], int >I<datalen>B<,>\n"
> > "B<           const unsigned char *>I<newrr>B<,>\n"
> > "B<           unsigned char >I<buf>B<[>I<buflen>B<], int >I<buflen>B<);>\n"
> 
> -- 
> <https://www.alejandro-colomar.es/>

Greetings

        Helge

-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

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

Re: Issue in man page resolver.3

[Alejandro Colomar]

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

Hi Helge,

On Sun, Aug 24, 2025 at 04:23:38PM +0000, Helge Kreutzmann wrote:
> Hello Alejandro,
> Am Sun, Aug 24, 2025 at 06:05:31PM +0200 schrieb Alejandro Colomar:
> > On Sun, Aug 24, 2025 at 02:48:32PM +0000, Helge Kreutzmann wrote:
> > > Without further ado, the following was found:
> > > 
> > > Issue:    B<…>int datalen, int buflen → B<…int> I<datalen>, B<int> I<buflen>
> > 
> > That is on purpose; it's a list of forward-declarations of parameters,
> > not the parameters themselves.  To distinguish them from actual
> > parameters, they're in Roman.  (Note the semicolon at the end of the
> > list of forward declarations.)
> 
> That is quite confusing, at least to me as a translator (not a
> programmer).


> So they are neither the function themselv (which is in
> bold) nor variables (which are in italics)?

Correct.

They are used to be able to refer to them in array size expressions
before the actual parameter has been declared.

> And the type (here "int")
> is printed in Roman on purpose, while it would be bold otherwise (see
> below, for e.g. "op", the type is in bold).

Yes, both the type and the parameter are in Roman, to gray the entire
list of forward declarations out.

> And in some pages, only a few of these are actually "forward
> parameters", while some others are not?

The list of forward declarations of parameters is up to the ';'.

> (But I trust you - if you say
> this is correct, then I simply align).
> 
> And: The name, in this example "datalen", comes from somewhere else
> ("forward")? I'm asking this because I would like to understand the
> implications of these "forward parameters" compared to normal
> parameters for translations.

Let's take strncpy(3), which is a simpler example:

       char *strncpy(size_t dsize;
                     char dst[restrict dsize], const char *restrict src,
                     size_t dsize);

everything between (.*; is the list of forward declarations.  It can
forward-declare parameters that must be declared again between ;.*) and
the declarations must be compatible.

I use a newline after the ';' to make the separation between forward
declarations of parameters and actual declarations of parameters more
readable.

Here, 'dsize' is forward-declared to be able to use it in the
declaration of 'dst[dsize]'.  Otherwise, 'dsize' would be undeclared.

Here's an example with GCC:

	alx@debian:~/tmp$ cat strncpy.c | nl -ba
	     1	#include <stddef.h>
	     2	
	     3	// Bad: dsize not declared before use
	     4	char *bad1(char dst[dsize], const char *restrict src, size_t dsize);
	     5	
	     6	// Bad: type mismatch
	     7	char *bad2(int dsize;
	     8	    char dst[dsize], const char *restrict src, size_t dsize);
	     9	
	    10	// Bad: foo is not a parameter
	    11	char *bad3(int foo;
	    12	    char dst[dsize], const char *restrict src, size_t dsize);
	    13	
	    14	char *good(size_t dsize;
	    15	    char dst[dsize], const char *restrict src, size_t dsize);
	alx@debian:~/tmp$ gcc -Wall -Wextra strncpy.c 
	strncpy.c:4:21: error: ‘dsize’ undeclared here (not in a function)
	    4 | char *bad1(char dst[dsize], const char *restrict src, size_t dsize);
	      |                     ^~~~~
	strncpy.c:8:55: error: conflicting types for ‘dsize’; have ‘size_t’ {aka ‘long unsigned int’}
	    8 |     char dst[dsize], const char *restrict src, size_t dsize);
	      |                                                ~~~~~~~^~~~~
	strncpy.c:7:16: note: previous definition of ‘dsize’ with type ‘int’
	    7 | char *bad2(int dsize;
	      |            ~~~~^~~~~
	strncpy.c:7:16: error: parameter ‘dsize’ has just a forward declaration
	strncpy.c:12:14: error: ‘dsize’ undeclared here (not in a function)
	   12 |     char dst[dsize], const char *restrict src, size_t dsize);
	      |              ^~~~~
	strncpy.c:11:16: error: parameter ‘foo’ has just a forward declaration
	   11 | char *bad3(int foo;
	      |            ~~~~^~~

> (Or do you have a reference, which explains this, than I will gladly
> have a look at it).

They are a GNU C extension.  They are documented here:

<https://gcc.gnu.org/onlinedocs/gcc/Variable-Length.html>

And they have been proposed for standardization into ISO C2y here:

<https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3433.pdf>

> > Have a lovely day!
> 
> You too.

:-)


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

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

Re: Issue in man page resolver.3

[Helge Kreutzmann]

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

Hello Alejandro,
thanks for the verbose explanation.

On (hoepfully) finale question:
This new formatting is not (yet?) reflected in man-pages(7)?a

Greetings

         Helge
-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

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

Re: Issue in man page resolver.3

[Alejandro Colomar]

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

Hi Helge,

On Mon, Aug 25, 2025 at 03:51:52PM +0000, Helge Kreutzmann wrote:
> Hello Alejandro,
> thanks for the verbose explanation.
> 
> On (hoepfully) finale question:
> This new formatting is not (yet?) reflected in man-pages(7)?a

Correct, not yet in man-pages(7).  I should note it there soon-ish.


Have a lovely night!
Alex

> 
> Greetings
> 
>          Helge
> -- 
>       Dr. Helge Kreutzmann                     debian@helgefjell.de
>            Dipl.-Phys.                   http://www.helgefjell.de/debian.php
>         64bit GNU powered                     gpg signed mail preferred
>            Help keep free software "libre": http://www.ffii.de/



-- 
<https://www.alejandro-colomar.es/>

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

Re: Issue in man page resolver.3

[Alejandro Colomar]

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

Hi Helge,

On Mon, Aug 25, 2025 at 03:51:52PM +0000, Helge Kreutzmann wrote:
> Hello Alejandro,
> thanks for the verbose explanation.
> 
> On (hoepfully) finale question:
> This new formatting is not (yet?) reflected in man-pages(7)?a

I have applied a patch documenting this.  Thanks for the report!


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

Re: Issue in man page resolver.3

[Vladimír Čunát]

Hello, just my 2c.

 > That is quite confusing, at least to me as a translator

I believe the forward syntax is confusing to C programmers, too.
It's not standard C and it's also not commonly used in code,
from what I see.  (at least so far; maybe in future)


Thanks for maintaining man-pages, by the way :-)
--Vladimir

Re: Issue in man page resolver.3

[Alejandro Colomar]

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

Hi Vladimír,

On Mon, Jan 26, 2026 at 10:21:38AM +0100, Vladimír Čunát wrote:
> Hello, just my 2c.
> 
> > That is quite confusing, at least to me as a translator
> 
> I believe the forward syntax is confusing to C programmers, too.
> It's not standard C and it's also not commonly used in code,
> from what I see.  (at least so far; maybe in future)

I can see it being somewhat confusing (as any new syntax, I guess).
I hope in the future it is not, and using it in the manual pages could
help with that.  And hopefully it also helps people use it more often.

> Thanks for maintaining man-pages, by the way :-)

You're welcome!  :-)


> --Vladimir

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

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

Issue in man page resolver.3

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    B<…>int anslen → B<…int> I<anslen>

"B<int res_nquery(>int anslen;\n"
"B<           res_state >I<statep>B<,>\n"
"B<           const char *>I<dname>B<, int >I<class>B<, int >I<type>B<,>\n"
"B<           unsigned char >I<answer>B<[>I<anslen>B<], int >I<anslen>B<);>\n"

"B<int res_nsearch(>int anslen;\n"
"B<           res_state >I<statep>B<,>\n"
"B<           const char *>I<dname>B<, int >I<class>B<, int >I<type>B<,>\n"
"B<           unsigned char >I<answer>B<[>I<anslen>B<], int >I<anslen>B<);>\n"

"B<int res_nquerydomain(>int anslen;\n"
"B<           res_state >I<statep>B<,>\n"
"B<           const char *>I<name>B<, const char *>I<domain>B<,>\n"
"B<           int >I<class>B<, int >I<type>B<, unsigned char >I<answer>B<[>I<anslen>B<],>\n"
"B<           int >I<anslen>B<);>\n"

"B<[[deprecated]]>\n"
"B<int res_query(>int anslen;\n"
"B<           const char *>I<dname>B<, int >I<class>B<, int >I<type>B<,>\n"
"B<           unsigned char >I<answer>B<[>I<anslen>B<], int >I<anslen>B<);>\n"

"B<[[deprecated]]>\n"
"B<int res_search(>int anslen;\n"
"B<           const char *>I<dname>B<, int >I<class>B<, int >I<type>B<,>\n"
"B<           unsigned char >I<answer>B<[>I<anslen>B<], int >I<anslen>B<);>\n"

"B<[[deprecated]]>\n"
"B<int res_querydomain(>int anslen;\n"
"B<           const char *>I<name>B<, const char *>I<domain>B<,>\n"
"B<           int >I<class>B<, int >I<type>B<, unsigned char >I<answer>B<[>I<anslen>B<],>\n"
"B<           int >I<anslen>B<);>\n"

Issue in man page resolver.3

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    B<…>int msglen, int anslen → B<…int> I<msglen>, B<int> I<anslen>

"B<[[deprecated]]>\n"
"B<int res_send(>int msglen, int anslen;\n"
"B<           const unsigned char >I<msg>B<[>I<msglen>B<], int >I<msglen>B<,>\n"
"B<           unsigned char >I<answer>B<[>I<anslen>B<], int >I<anslen>B<);>\n"

Issue in man page resolver.3

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    B<…>int datalen, int buflen → B<…int> I<datalen>, B<int> I<buflen>

"B<[[deprecated]]>\n"
"B<int res_mkquery(>int datalen, int buflen;\n"
"B<           int >I<op>B<, const char *>I<dname>B<, int >I<class>B<,>\n"
"B<           int >I<type>B<, const unsigned char >I<data>B<[>I<datalen>B<], int >I<datalen>B<,>\n"
"B<           const unsigned char *>I<newrr>B<,>\n"
"B<           unsigned char >I<buf>B<[>I<buflen>B<], int >I<buflen>B<);>\n"

Issue in man page resolver.3

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    B<…>int msglen, int anslen → B<…int> I<msglen>, B<int> I<anslen>

"B<int res_nsend(>int msglen, int anslen;\n"
"B<           res_state >I<statep>B<,>\n"
"B<           const unsigned char >I<msg>B<[>I<msglen>B<], int >I<msglen>B<,>\n"
"B<           unsigned char >I<answer>B<[>I<anslen>B<], int >I<anslen>B<);>\n"

Issue in man page resolver.3

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    B<…>int length → B<…int> I<length>

"B<int dn_comp(>int length;\n"
"B<           const char *>I<exp_dn>B<, unsigned char >I<comp_dn>B<[>I<length>B<],>\n"
"B<           int >I<length>B<, unsigned char **>I<dnptrs>B<,>\n"
"B<           unsigned char **>I<lastdnptr>B<);>\n"

"B<int dn_expand(>int length;\n"
"B<           const unsigned char *>I<msg>B<,>\n"
"B<           const unsigned char *>I<eomorig>B<,>\n"
"B<           const unsigned char *>I<comp_dn>B<, char >I<exp_dn>B<[>I<length>B<],>\n"
"B<           int >I<length>B<);>\n"