Missing header file in synopsis section of authenticate(3) man page.
Hi, Isn't the header file 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: salva...@gmail.com
Re: Missing header file in synopsis section of authenticate(3) man page.
On Tue, Jun 30, 2009 at 08:56:36AM -0300, Jo?o Salvatti wrote: > Hi, > > Isn't the header file 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
Re: Missing header file in synopsis section of authenticate(3) man page.
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 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 or without including
will make your program not compile.
The header uses quad_t and uid_t.
The type quad_t is a non-POSIX type defined in .
The type uid_t is required by POSIX in .
The header uses size_t.
The type size_t is required by POSIX in .
> 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 ,
both some traditional BSD headers like and some POSIX headers
like .
Probably, this went unnoticed because most programs including
the headers and also include some
of the other headers including , like ,
, and ...
If i understand correctly, headers using types from
ought to include
- 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 - 1.9
+++ bsd_auth.h 5 Jul 2009 19:51:35 -
@@ -52,6 +52,8 @@ typedef enum {
} auth_item_t;
#include
+#include
+
__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 - 1.13
+++ login_cap.h 5 Jul 2009 19:51:35 -
@@ -88,6 +88,8 @@ typedef struct login_cap {
} login_cap_t;
#include
+#include
+
__BEGIN_DECLS
struct passwd;
Re: Missing header file in synopsis section of authenticate(3) man page.
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 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.
Re: Missing header file in synopsis section of authenticate(3) man page.
> Date: Sun, 5 Jul 2009 21:58:35 +0200 > From: Ingo Schwarze > > The header uses quad_t and uid_t. > The type quad_t is a non-POSIX type defined in . > The type uid_t is required by POSIX in . > > The header uses size_t. > The type size_t is required by POSIX in . > > > 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 , > both some traditional BSD headers like and some POSIX headers > like . > > Probably, this went unnoticed because most programs including > the headers and also include some > of the other headers including , like , > , and ... > > If i understand correctly, headers using types from > ought to include > - 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 . Mark
Re: Missing header file in synopsis section of authenticate(3) man page.
> > If i understand correctly, headers using types from > > ought to include > > - 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 . 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.
Re: Missing header file in synopsis section of authenticate(3) man page.
On Sun, Jul 05, 2009 at 10:19:14PM +0200, Mark Kettenis wrote: > > So I think the man pages should be amended to #include . > 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
Re: Missing header file in synopsis section of authenticate(3) man page.
> Date: Sun, 05 Jul 2009 14:48:14 -0600 > From: Theo de Raadt > > > > If i understand correctly, headers using types from > > > ought to include > > > - 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 . > > 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.
Re: Missing header file in synopsis section of authenticate(3) man page.
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 - 1.18 +++ auth_subr.3 5 Jul 2009 20:53:43 - @@ -58,6 +58,7 @@ .Nm auth_setstate .Nd interface to the BSD Authentication system .Sh SYNOPSIS +.Fd #include .Fd #include .Fd #include .Ft auth_session_t *
Re: Missing header file in synopsis section of authenticate(3) man page.
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 . > 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 before including or . > 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 - 1.11 +++ authenticate.3 5 Jul 2009 21:18:07 - @@ -46,6 +46,7 @@ .Nm auth_verify .Nd simplified interface to the BSD Authentication system .Sh SYNOPSIS +.Fd #include .Fd #include .Fd #include .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 - 1.18 +++ auth_subr.3 5 Jul 2009 21:18:07 - @@ -58,6 +58,7 @@ .Nm auth_setstate .Nd interface to the BSD Authentication system .Sh SYNOPSIS +.Fd #include .Fd #include .Fd #include .Ft auth_session_t *
Re: Missing header file in synopsis section of authenticate(3) man page.
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
