Missing header file in synopsis section of authenticate(3) man page.

classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|

Missing header file in synopsis section of authenticate(3) man page.

João Salvatti
Hi,

Isn't the header file <sys/types.h> absent in the manual page
authenticate(3)? The use of its functions, such as auth_userokay(),
will never compile without the inclusion of that header.

Thanks in advance.

--
Joco Salvatti
Graduated in Computer Science
Federal University of Para - UFPA - Brazil
E-Mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Missing header file in synopsis section of authenticate(3) man page.

Jason McIntyre-2
On Tue, Jun 30, 2009 at 08:56:36AM -0300, Jo?o Salvatti wrote:
> Hi,
>
> Isn't the header file <sys/types.h> absent in the manual page
> authenticate(3)? The use of its functions, such as auth_userokay(),
> will never compile without the inclusion of that header.
>
> Thanks in advance.
>

no one has replied to this yet, i think. so, the man page is right or
wrong? any takers?

jmc

Reply | Threaded
Open this post in threaded view
|

Re: Missing header file in synopsis section of authenticate(3) man page.

Ingo Schwarze
Hi Jason,

Jason McIntyre wrote on Sun, Jul 05, 2009 at 05:46:06PM +0100:
> On Tue, Jun 30, 2009 at 08:56:36AM -0300, Joao Salvatti wrote:

>> Isn't the header file <sys/types.h> absent in the manual page
>> authenticate(3)?

Yes, it is absent, but grepping /usr/share/man/cat3 for "types.h"
tells me that sys/types.h is not mentioned in a single section 3
manual page.

>> The use of its functions, such as auth_userokay(),
>> will never compile without the inclusion of that header.

Right, even without actually using any of the functions,
including either <login_cap.h> or <bsd_auth.h> without including
<sys/types.h> will make your program not compile.

The header <login_cap.h> uses quad_t and uid_t.
The type quad_t is a non-POSIX type defined in <sys/types.h>.
The type uid_t is required by POSIX in <sys/types.h>.

The header <bsd_auth.h> uses size_t.
The type size_t is required by POSIX in <sys/types.h>.

> no one has replied to this yet, i think. so, the man page is right or
> wrong? any takers?

I guess the manual is fine, but i'm not sure these two header files
are correct.  Lots of other header files include <sys/types.h>,
both some traditional BSD headers like <db.h> and some POSIX headers
like <fcntl.h>.

Probably, this went unnoticed because most programs including
the headers <login_cap.h> and <bsd_auth.h> also include some
of the other headers including <sys/types.h>, like <pwd.h>,
<stdio.h>, <stdlib.h> and <unistd.h>...

If i understand correctly, headers using types from <sys/types.h>
ought to include <sys/types.h>
 - unconditionally, if they are POSIX headers and the use of the
   type is mandated by POSIX
 - protected by __BSD_VISIBLE or the appropriate feature macro
   like __XPG_VISIBLE, if they are POSIX headers and if the use
   is not mandated by POSIX, but by a lesser standard
 - protected by __BSD_VISIBLE only, if they are POSIX headers and
   if the use is not mandated by a standard
 - unconditionally, if they are not POSIX headers

Here, the latter case applies, so i suggest the following diff.
Feel free to apply the cluestick in case i got this wrong...

Yours,
  Ingo


Index: bsd_auth.h
===================================================================
RCS file: /cvs/src/include/bsd_auth.h,v
retrieving revision 1.9
diff -u -p -r1.9 bsd_auth.h
--- bsd_auth.h 6 Jan 2006 18:53:04 -0000 1.9
+++ bsd_auth.h 5 Jul 2009 19:51:35 -0000
@@ -52,6 +52,8 @@ typedef enum {
 } auth_item_t;
 
 #include <sys/cdefs.h>
+#include <sys/types.h>
+
 __BEGIN_DECLS
 struct passwd;
 struct login_cap;
Index: login_cap.h
===================================================================
RCS file: /cvs/src/include/login_cap.h,v
retrieving revision 1.13
diff -u -p -r1.13 login_cap.h
--- login_cap.h 28 Jan 2005 17:17:22 -0000 1.13
+++ login_cap.h 5 Jul 2009 19:51:35 -0000
@@ -88,6 +88,8 @@ typedef struct login_cap {
 } login_cap_t;
 
 #include <sys/cdefs.h>
+#include <sys/types.h>
+
 __BEGIN_DECLS
 struct passwd;

Reply | Threaded
Open this post in threaded view
|

Re: Missing header file in synopsis section of authenticate(3) man page.

ian@
Ingo Schwarze wrote:

> Hi Jason,
>
> Jason McIntyre wrote on Sun, Jul 05, 2009 at 05:46:06PM +0100:
>  
>> On Tue, Jun 30, 2009 at 08:56:36AM -0300, Joao Salvatti wrote:
>>    
>>> Isn't the header file <sys/types.h> absent in the manual page
>>> authenticate(3)?
>>>      
>
> Yes, it is absent, but grepping /usr/share/man/cat3 for "types.h"
> tells me that sys/types.h is not mentioned in a single section 3
> manual page.
>
>  
There's no value getting the wrong answer quickly.

cd /usr/src/lib; find . -name \*.3 | xargs grep 'sys.types.h' |
> wc -l
>       51

Anyway, it's on hold til after the unlock.

Reply | Threaded
Open this post in threaded view
|

Re: Missing header file in synopsis section of authenticate(3) man page.

Mark Kettenis
In reply to this post by Ingo Schwarze
> Date: Sun, 5 Jul 2009 21:58:35 +0200
> From: Ingo Schwarze <[hidden email]>
>
> The header <login_cap.h> uses quad_t and uid_t.
> The type quad_t is a non-POSIX type defined in <sys/types.h>.
> The type uid_t is required by POSIX in <sys/types.h>.
>
> The header <bsd_auth.h> uses size_t.
> The type size_t is required by POSIX in <sys/types.h>.
>
> > no one has replied to this yet, i think. so, the man page is right or
> > wrong? any takers?
>
> I guess the manual is fine, but i'm not sure these two header files
> are correct.  Lots of other header files include <sys/types.h>,
> both some traditional BSD headers like <db.h> and some POSIX headers
> like <fcntl.h>.
>
> Probably, this went unnoticed because most programs including
> the headers <login_cap.h> and <bsd_auth.h> also include some
> of the other headers including <sys/types.h>, like <pwd.h>,
> <stdio.h>, <stdlib.h> and <unistd.h>...
>
> If i understand correctly, headers using types from <sys/types.h>
> ought to include <sys/types.h>
>  - unconditionally, if they are POSIX headers and the use of the
>    type is mandated by POSIX
>  - protected by __BSD_VISIBLE or the appropriate feature macro
>    like __XPG_VISIBLE, if they are POSIX headers and if the use
>    is not mandated by POSIX, but by a lesser standard
>  - protected by __BSD_VISIBLE only, if they are POSIX headers and
>    if the use is not mandated by a standard
>  - unconditionally, if they are not POSIX headers

You have the latter case wrong.  We tend to not include header files
in other header files, unless mandated by some standard.

So I think the man pages should be amended to #include <sys/types.h>.

Mark

Reply | Threaded
Open this post in threaded view
|

Re: Missing header file in synopsis section of authenticate(3) man page.

Theo de Raadt
> > If i understand correctly, headers using types from <sys/types.h>
> > ought to include <sys/types.h>
> >  - unconditionally, if they are POSIX headers and the use of the
> >    type is mandated by POSIX
> >  - protected by __BSD_VISIBLE or the appropriate feature macro
> >    like __XPG_VISIBLE, if they are POSIX headers and if the use
> >    is not mandated by POSIX, but by a lesser standard
> >  - protected by __BSD_VISIBLE only, if they are POSIX headers and
> >    if the use is not mandated by a standard
> >  - unconditionally, if they are not POSIX headers
>
> You have the latter case wrong.  We tend to not include header files
> in other header files, unless mandated by some standard.
>
> So I think the man pages should be amended to #include <sys/types.h>.

Mark is correct.  It is simply a documentation error.

If we went the other way around, people would be able to include less
files; indeed, almost be careless about what they include.  But this
would not increase portability in any way.  And 'make build' would
probably, if it was taken the nth degree, take twice as long.
Therefore there is no benefit for the crazy rule you suggest which I
am going to call "pull in the world".

To be even more silly, there is another way to "pull in the world".  We
simply put all of the includes into "sys/types.h" with protection, and
make all the other include files a hard link.  Ha ha.

Reply | Threaded
Open this post in threaded view
|

Re: Missing header file in synopsis section of authenticate(3) man page.

Jason McIntyre-2
In reply to this post by Mark Kettenis
On Sun, Jul 05, 2009 at 10:19:14PM +0200, Mark Kettenis wrote:
>
> So I think the man pages should be amended to #include <sys/types.h>.
>

pages (plural)? there are more than this one to fix?

if so, can someone put a diff together and fix it (post lock). even if
it's only the one page, someone other than me should fix it, since there
is an ordering to header files that i don;t know about it (and have no
wish to know about, before some kind soul tries to enlighten me).

so, in summary, once we are out of lock, can someone please fix this.
thanks,

jmc

Reply | Threaded
Open this post in threaded view
|

Re: Missing header file in synopsis section of authenticate(3) man page.

Mark Kettenis
In reply to this post by Theo de Raadt
> Date: Sun, 05 Jul 2009 14:48:14 -0600
> From: Theo de Raadt <[hidden email]>
>
> > > If i understand correctly, headers using types from <sys/types.h>
> > > ought to include <sys/types.h>
> > >  - unconditionally, if they are POSIX headers and the use of the
> > >    type is mandated by POSIX
> > >  - protected by __BSD_VISIBLE or the appropriate feature macro
> > >    like __XPG_VISIBLE, if they are POSIX headers and if the use
> > >    is not mandated by POSIX, but by a lesser standard
> > >  - protected by __BSD_VISIBLE only, if they are POSIX headers and
> > >    if the use is not mandated by a standard
> > >  - unconditionally, if they are not POSIX headers
> >
> > You have the latter case wrong.  We tend to not include header files
> > in other header files, unless mandated by some standard.
> >
> > So I think the man pages should be amended to #include <sys/types.h>.
>
> Mark is correct.  It is simply a documentation error.
>
> If we went the other way around, people would be able to include less
> files; indeed, almost be careless about what they include.  But this
> would not increase portability in any way.  And 'make build' would
> probably, if it was taken the nth degree, take twice as long.

Or worse, you end up with circular dependencies.

Reply | Threaded
Open this post in threaded view
|

Re: Missing header file in synopsis section of authenticate(3) man page.

Ingo Schwarze
In reply to this post by ian@
Ian Darwin wrote on Sun, Jul 05, 2009 at 04:18:00PM -0400:

> There's no value getting the wrong answer quickly.

Ouch.
I should have noticed, i did look at getgrent(3) and such before.
Thanks for the explanations and sorry for wasting your time...

So i will simply do the following *after unlock*:


Index: auth_subr.3
===================================================================
RCS file: /cvs/src/lib/libc/gen/auth_subr.3,v
retrieving revision 1.18
diff -u -p -r1.18 auth_subr.3
--- auth_subr.3 4 Apr 2008 17:42:39 -0000 1.18
+++ auth_subr.3 5 Jul 2009 20:53:43 -0000
@@ -58,6 +58,7 @@
 .Nm auth_setstate
 .Nd interface to the BSD Authentication system
 .Sh SYNOPSIS
+.Fd #include <sys/types.h>
 .Fd #include <login_cap.h>
 .Fd #include <bsd_auth.h>
 .Ft auth_session_t *

Reply | Threaded
Open this post in threaded view
|

Re: Missing header file in synopsis section of authenticate(3) man page.

Ingo Schwarze
In reply to this post by Jason McIntyre-2
Jason McIntyre wrote on Sun, Jul 05, 2009 at 09:52:13PM +0100:
> On Sun, Jul 05, 2009 at 10:19:14PM +0200, Mark Kettenis wrote:

>> So I think the man pages should be amended to #include <sys/types.h>.

> pages (plural)? there are more than this one to fix?

Indeed, *two* need a fix, whereas login_cap(3) is already fine.

Even though the functions documented in authenticate(3) do not directly
use quad_t, size_t or uid_t, that's irrelevant, you always need to
include <sys/types.h> before including <login_cap.h> or <bsd_auth.h>.

> so, in summary, once we are out of lock, can someone please fix this.

Yes.


Index: authenticate.3
===================================================================
RCS file: /cvs/src/lib/libc/gen/authenticate.3,v
retrieving revision 1.11
diff -u -p -r1.11 authenticate.3
--- authenticate.3 4 Apr 2008 17:42:39 -0000 1.11
+++ authenticate.3 5 Jul 2009 21:18:07 -0000
@@ -46,6 +46,7 @@
 .Nm auth_verify
 .Nd simplified interface to the BSD Authentication system
 .Sh SYNOPSIS
+.Fd #include <sys/types.h>
 .Fd #include <login_cap.h>
 .Fd #include <bsd_auth.h>
 .Ft int
Index: auth_subr.3
===================================================================
RCS file: /cvs/src/lib/libc/gen/auth_subr.3,v
retrieving revision 1.18
diff -u -p -r1.18 auth_subr.3
--- auth_subr.3 4 Apr 2008 17:42:39 -0000 1.18
+++ auth_subr.3 5 Jul 2009 21:18:07 -0000
@@ -58,6 +58,7 @@
 .Nm auth_setstate
 .Nd interface to the BSD Authentication system
 .Sh SYNOPSIS
+.Fd #include <sys/types.h>
 .Fd #include <login_cap.h>
 .Fd #include <bsd_auth.h>
 .Ft auth_session_t *

Reply | Threaded
Open this post in threaded view
|

Re: Missing header file in synopsis section of authenticate(3) man page.

Jason McIntyre-2
On Sun, Jul 05, 2009 at 11:27:35PM +0200, Ingo Schwarze wrote:
>
> > so, in summary, once we are out of lock, can someone please fix this.
>
> Yes.
>

thanks.
jmc