"Writing" instead of "Warning" in dlopen(3) manpage

"Writing" instead of "Warning" in dlopen(3) manpage

[noname-CuI0ZDT4mYnsrOwW+9ziJQ]

dlopen C code example contains following comment:

/* Writing: cosine = (double (*)(double)) dlsym(handle, "cos");
   ... */

"Writing:" should be replaced with "Warning:".
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: "Writing" instead of "Warning" in dlopen(3) manpage

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 611 bytes --]

On Tuesday 31 December 2013 07:42:09 noname-CuI0ZDT4mYnsrOwW+9ziJQ@public.gmane.org wrote:
> dlopen C code example contains following comment:
> 
> /* Writing: cosine = (double (*)(double)) dlsym(handle, "cos");
>    ... */
> 
> "Writing:" should be replaced with "Warning:".

both are correct

however, i wonder if the comment should be inverted.  the latest POSIX spec 
requires that the natural cast work.
http://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html#tag_16_96_07

Linux man pages document the normal Linux environment, and that means POSIX, 
not strict ISO C.
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: "Writing" instead of "Warning" in dlopen(3) manpage

[Michael Kerrisk (man-pages)]

On 01/01/14 05:19, Mike Frysinger wrote:
> On Tuesday 31 December 2013 07:42:09 noname-CuI0ZDT4mYnsrOwW+9ziJQ@public.gmane.org wrote:
>> dlopen C code example contains following comment:
>>
>> /* Writing: cosine = (double (*)(double)) dlsym(handle, "cos");
>>    ... */
>>
>> "Writing:" should be replaced with "Warning:".
> 
> both are correct
> 
> however, i wonder if the comment should be inverted.  the latest POSIX spec 
> requires that the natural cast work.
> http://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html#tag_16_96_07
> 
> Linux man pages document the normal Linux environment, and that means POSIX, 
> not strict ISO C.

Thanks for your comments Mike. It's been at the back of my mind for a while now
to do something about this. I applied the patch below. Look okay to you?

Cheers,

Michael


diff --git a/man3/dlopen.3 b/man3/dlopen.3
index dd54120..47ca55f 100644
--- a/man3/dlopen.3
+++ b/man3/dlopen.3
@@ -466,15 +466,22 @@ main(int argc, char **argv)
 
     dlerror();    /* Clear any existing error */
 
-    /* Writing: cosine = (double (*)(double)) dlsym(handle, "cos");
-       would seem more natural, but the C99 standard leaves
-       casting from "void *" to a function pointer undefined.
-       The assignment used below is the POSIX.1\-2003 (Technical
-       Corrigendum 1) workaround; see the Rationale for the
-       POSIX specification of dlsym(). */
+    cosine = (double (*)(double)) dlsym(handle, "cos");
 
-    *(void **) (&cosine) = dlsym(handle, "cos");
-.\" But in fact "gcc -O2 -Wall" will complain about the preceding cast.
+    /* According to the C99 standard, casting 'void *' to a function pointer
+       as shown above is forbidden. POSIX.1-2003 and POSIX.2008 followed
+       C99's requirement, and proposed the following workaround:
+
+           *(void **) (&cosine) = dlsym(handle, "cos");
+
+       This (clumsy) cast conforms with C99 and will avoid any compiler 
+       warnings.
+
+       The 2013 Technical Corrigendum to POSIX.1-2008 (a.k.a. POSIX.1-2013)
+       improved matters by requiring that conforming implementations support
+       casting 'void *' to a function pointer. Nevertheless, some compilers
+       (e.g., gcc with the '-pedantic' option) may complain about the cast
+       used in this program. */



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: "Writing" instead of "Warning" in dlopen(3) manpage

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 2127 bytes --]

On Wednesday 01 January 2014 20:46:59 Michael Kerrisk (man-pages) wrote:
> --- a/man3/dlopen.3
> +++ b/man3/dlopen.3
> 
> /* According to the C99 standard, casting 'void *' to a function pointer
> as shown above is forbidden. POSIX.1-2003 and POSIX.2008 followed
> C99's requirement, and proposed the following workaround:

i don't want to be pedantic, buuuuut:
 - you want to say "ISO C" rather than "C99"
 - the spec says that it is "undefined behavior" rather than "forbidden"

i wonder about deleting the "followed C99's requirement" part.  they aren't 
really following the requirement since (at least 2008) says that it must be 
supported.

the "POSIX.2008" probably should be "POSIX.1-2008".  or maybe just change it 
to "POSIX.1" ?

> +           *(void **) (&cosine) = dlsym(handle, "cos");
> +
> +       This (clumsy) cast conforms with C99 and will avoid any compiler
> +       warnings.

might it be worth suggesting a union too ?
	double (*cosine)(double);
	union {
		void *vptr;
		double (*ptr)(double);
	} cast;
	cast.vptr = dlsym(...);
	cosine = cast.double;

i think this also avoids aliasing warnings and works nicely in C++ ?  or i 
could be making this up entirely :).

> The 2013 Technical Corrigendum to POSIX.1-2008 (a.k.a. POSIX.1-2013)
> improved matters by requiring that conforming implementations support
> casting 'void *' to a function pointer.

how about adding a comment inside of the man page itself linking to the POSIX 
pages ?  making it visible to end users might be too much, but for people 
maintaining the comments (i.e. you) would be good.
http://pubs.opengroup.org/onlinepubs/009695399/functions/dlsym.html#tag_03_112_08
http://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html#tag_16_96_07

> Nevertheless, some compilers
> (e.g., gcc with the '-pedantic' option) may complain about the cast
> used in this program. */

three things:
 - i think the ISO C standard is required to at least emit a warning
 - i was going to suggest the -pedantic thing :)
 - seriously, you're using "e.g." after chastising me ? :D
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: "Writing" instead of "Warning" in dlopen(3) manpage

[Michael Kerrisk (man-pages)]

Hi Mike,

Thanks for following up.

On Thu, Jan 2, 2014 at 5:06 PM, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
> On Wednesday 01 January 2014 20:46:59 Michael Kerrisk (man-pages) wrote:
>> --- a/man3/dlopen.3
>> +++ b/man3/dlopen.3
>>
>> /* According to the C99 standard, casting 'void *' to a function pointer
>> as shown above is forbidden. POSIX.1-2003 and POSIX.2008 followed
>> C99's requirement, and proposed the following workaround:
>
> i don't want to be pedantic, buuuuut:
>  - you want to say "ISO C" rather than "C99"

Yes, good point. Fixed now.

>  - the spec says that it is "undefined behavior" rather than "forbidden"

Likewise; fixed now.

> i wonder about deleting the "followed C99's requirement" part.  they aren't
> really following the requirement since (at least 2008) says that it must be
> supported.

Yes, the language could be better. I changed it to "[they] accepted
this state of affairs"

> the "POSIX.2008" probably should be "POSIX.1-2008".  or maybe just change it
> to "POSIX.1" ?

POSIX.1-2008.

>> +           *(void **) (&cosine) = dlsym(handle, "cos");
>> +
>> +       This (clumsy) cast conforms with C99 and will avoid any compiler
>> +       warnings.
>
> might it be worth suggesting a union too ?
>         double (*cosine)(double);
>         union {
>                 void *vptr;
>                 double (*ptr)(double);
>         } cast;
>         cast.vptr = dlsym(...);
>         cosine = cast.double;

I think I'll not worry about this.

> i think this also avoids aliasing warnings and works nicely in C++ ?  or i
> could be making this up entirely :).
>
>> The 2013 Technical Corrigendum to POSIX.1-2008 (a.k.a. POSIX.1-2013)
>> improved matters by requiring that conforming implementations support
>> casting 'void *' to a function pointer.
>
> how about adding a comment inside of the man page itself linking to the POSIX
> pages ?  making it visible to end users might be too much, but for people
> maintaining the comments (i.e. you) would be good.
> http://pubs.opengroup.org/onlinepubs/009695399/functions/dlsym.html#tag_03_112_08
> http://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html#tag_16_96_07

Yes, good idea.

>> Nevertheless, some compilers
>> (e.g., gcc with the '-pedantic' option) may complain about the cast
>> used in this program. */
>
> three things:
>  - i think the ISO C standard is required to at least emit a warning

Yes, but it's not quite clear to me if the POSIX.1-2013 is meaning
that compilers should not issue a warning in this case. Maybe I'm
misunderstanding something, though.

>  - i was going to suggest the -pedantic thing :)
>  - seriously, you're using "e.g." after chastising me ? :D

I don't recall chastising you as such... But, in running text using
"e.g." and "i.e." often does not work well, I find (and most style
manuals agree). As I said, mostly the only place you'll find these
forms in the man pages is in parenthetical asides, as is done here.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: "Writing" instead of "Warning" in dlopen(3) manpage

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 1262 bytes --]

On Thursday 02 January 2014 04:33:30 Michael Kerrisk (man-pages) wrote:
> On Thu, Jan 2, 2014 at 5:06 PM, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
> > On Wednesday 01 January 2014 20:46:59 Michael Kerrisk (man-pages) wrote:
> >> Nevertheless, some compilers
> >> (e.g., gcc with the '-pedantic' option) may complain about the cast
> >> used in this program. */
> > 
> > three things:
> >  - i think the ISO C standard is required to at least emit a warning
> 
> Yes, but it's not quite clear to me if the POSIX.1-2013 is meaning
> that compilers should not issue a warning in this case. Maybe I'm
> misunderstanding something, though.

true.  in this particular case, it's probably not worth being super pedantic 
since we covered our bases earlier on.

overall question: should the new comment block live above or below the example 
call ?  it's currently below, but i kind of favor putting it before.  i know 
as the content flows, the current one makes a bit of sense (show the right 
answer, and then as an aside, mention the portability issue), but the comment 
is specifically covering this line, so putting it above the line it is 
discussing is a bit more standard i think in the coding world.
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: "Writing" instead of "Warning" in dlopen(3) manpage

[Michael Kerrisk (man-pages)]

Hi Mike,

On Fri, Jan 3, 2014 at 1:33 AM, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
> On Thursday 02 January 2014 04:33:30 Michael Kerrisk (man-pages) wrote:
>> On Thu, Jan 2, 2014 at 5:06 PM, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
>> > On Wednesday 01 January 2014 20:46:59 Michael Kerrisk (man-pages) wrote:
>> >> Nevertheless, some compilers
>> >> (e.g., gcc with the '-pedantic' option) may complain about the cast
>> >> used in this program. */
>> >
>> > three things:
>> >  - i think the ISO C standard is required to at least emit a warning
>>
>> Yes, but it's not quite clear to me if the POSIX.1-2013 is meaning
>> that compilers should not issue a warning in this case. Maybe I'm
>> misunderstanding something, though.
>
> true.  in this particular case, it's probably not worth being super pedantic
> since we covered our bases earlier on.
>
> overall question: should the new comment block live above or below the example
> call ?  it's currently below, but i kind of favor putting it before.  i know
> as the content flows, the current one makes a bit of sense (show the right
> answer, and then as an aside, mention the portability issue), but the comment
> is specifically covering this line, so putting it above the line it is
> discussing is a bit more standard i think in the coding world.

I kind of prefer it as an aside, following the code, but I've now also
added some words to more explicitly indicate that the comment refers
to the code above it.

Cheers,

Michael

    cosine = (double (*)(double)) dlsym(handle, "cos");

    /* According to the ISO C standard, casting between function
       pointers and 'void *', as done above, produces undefined results.
       POSIX.1-2003 and POSIX.1-2008 accepted this state of affairs and
       proposed the following workaround:

           *(void **) (&cosine) = dlsym(handle, "cos");

       This (clumsy) cast conforms with ISO C standard and will avoid
       any compiler warnings.

       The 2013 Technical Corrigendum to POSIX.1-2008 (a.k.a.
       POSIX.1-2013) improved matters by requiring that conforming
       implementations support casting 'void *' to a function pointer.
       Nevertheless, some compilers (e.g., gcc with the '-pedantic'
       option) may complain about the cast used in this program. */

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: "Writing" instead of "Warning" in dlopen(3) manpage

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 1096 bytes --]

On Thursday 02 January 2014 14:20:50 Michael Kerrisk (man-pages) wrote:
>     /* According to the ISO C standard, casting between function
>        pointers and 'void *', as done above, produces undefined results.
>        POSIX.1-2003 and POSIX.1-2008 accepted this state of affairs and
>        proposed the following workaround:
> 
>            *(void **) (&cosine) = dlsym(handle, "cos");
> 
>        This (clumsy) cast conforms with ISO C standard and will avoid
>        any compiler warnings.

"with the ISO C standard"

>        The 2013 Technical Corrigendum to POSIX.1-2008 (a.k.a.
>        POSIX.1-2013)

i thought you wanted to avoid "a.k.a." ?  or does that not apply to 
parenthetical asides too ?

should all these random preferences be added in man-pages(7) ?  off the top of 
my head:
	- userspace vs user space vs user-space
	- a.k.a. / e.g. / i.e. usage
	- NUL usage (or lack thereof)
	- HISTORY should be a .SS of NOTES
	- wrapping based on periods/commas
	- preference for 75 cols

some of these could even be checks added to scripts/ ...
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: "Writing" instead of "Warning" in dlopen(3) manpage

[Michael Kerrisk (man-pages)]

On Fri, Jan 3, 2014 at 8:45 AM, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
> On Thursday 02 January 2014 14:20:50 Michael Kerrisk (man-pages) wrote:
>>     /* According to the ISO C standard, casting between function
>>        pointers and 'void *', as done above, produces undefined results.
>>        POSIX.1-2003 and POSIX.1-2008 accepted this state of affairs and
>>        proposed the following workaround:
>>
>>            *(void **) (&cosine) = dlsym(handle, "cos");
>>
>>        This (clumsy) cast conforms with ISO C standard and will avoid
>>        any compiler warnings.
>
> "with the ISO C standard"

Thanks.

>>        The 2013 Technical Corrigendum to POSIX.1-2008 (a.k.a.
>>        POSIX.1-2013)
>
> i thought you wanted to avoid "a.k.a." ?  or does that not apply to
> parenthetical asides too ?
>
> should all these random preferences be added in man-pages(7) ?  off the top of
> my head:
>         - userspace vs user space vs user-space
>         - a.k.a. / e.g. / i.e. usage
>         - NUL usage (or lack thereof)
>         - HISTORY should be a .SS of NOTES
>         - wrapping based on periods/commas
>         - preference for 75 cols

It's one of those things that's been on my TODO list for an age. I've
made a start now, by creating a STYLE GUIDE section in man-page(7).

> some of these could even be checks added to scripts/ ...

Yes, one day...

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html