From murduth@rmstar.campus.luth.se  Wed Jan 10 07:05:24 2001
Return-Path: <murduth@rmstar.campus.luth.se>
Received: from rmstar.campus.luth.se (rmstar.campus.luth.se [130.240.197.32])
	by hub.freebsd.org (Postfix) with ESMTP id 3420237B400
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 10 Jan 2001 07:05:23 -0800 (PST)
Received: from rmstar.campus.luth.se (localhost [127.0.0.1])
	by rmstar.campus.luth.se (8.11.1/8.9.3) with ESMTP id f0AF5LL23212
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 10 Jan 2001 16:05:21 +0100 (CET)
	(envelope-from murduth@rmstar.campus.luth.se)
Message-Id: <200101101505.f0AF5LL23212@rmstar.campus.luth.se>
Date: Wed, 10 Jan 2001 16:05:21 +0100
From: Joakim Henriksson <murduth@ludd.luth.se>
To: FreeBSD-gnats-submit@freebsd.org
Subject: Useless gethostbyaddr man page

>Number:         24225
>Category:       docs
>Synopsis:       man gethostbyaddr
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Jan 10 07:10:01 PST 2001
>Closed-Date:    Fri Feb 9 11:06:10 PST 2001
>Last-Modified:  Fri Feb 09 11:06:34 PST 2001
>Originator:     Joakim Henriksson
>Release:        FreeBSD 4.2-STABLE i386
>Organization:
Lule Tekniska Universitet
>Environment:

murduth@rmstar ~ >uname -a
FreeBSD rmstar.campus.luth.se 4.2-STABLE FreeBSD 4.2-STABLE #0: Wed Dec 27 
19:42:13 CET 2000     troot@rmstar.campus.luth.se:/usr/src/sys/compile/RMSTAR  
i386
murduth@rmstar ~ >


>Description:

The manual page for gethostbyaddr does not even describe what the arguments 
should be.

>How-To-Repeat:

murduth@rmstar ~ >man gethostbyaddr

>Fix:

Steal from linux or solaris.
-- 
regards/ Joakim



>Release-Note:
>Audit-Trail:

From: Ben Smithurst <ben@FreeBSD.org>
To: Joakim Henriksson <murduth@ludd.luth.se>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/24225: Useless gethostbyaddr man page
Date: Wed, 10 Jan 2001 16:17:26 +0000

 Joakim Henriksson wrote:
 
 > The manual page for gethostbyaddr does not even describe what the arguments 
 > should be.
 
 ok, what do you (and everyone else) think of this patch?
 
 Index: gethostbyname.3
 ===================================================================
 RCS file: /usr/cvs/src/lib/libc/net/gethostbyname.3,v
 retrieving revision 1.14
 diff -u -r1.14 gethostbyname.3
 --- gethostbyname.3	2000/09/06 18:16:40	1.14
 +++ gethostbyname.3	2001/01/10 16:14:20
 @@ -76,7 +76,34 @@
  each return a pointer to an object with the
  following structure describing an internet host
  referenced by name or by address, respectively.
 -This structure contains either the information obtained from the name server,
 +.Pp
 +The
 +.Fa name
 +parameter passed to
 +.Fn gethostbyname
 +or
 +.Fn gethostbyname2
 +should point to a NUL-terminated hostname.
 +The
 +.Fa addr
 +parameter passed to
 +.Fn gethostbyaddr
 +should point to an address which is
 +.Fa len
 +bytes long,
 +in binary form
 +(i.e. not an IP address in human readable ASCII form).
 +The
 +.Fa type
 +parameter specifies the address family
 +(e.g.
 +.Dv AF_INET ,
 +.Dv AF_INET6 ,
 +etc)
 +of this address.
 +.Pp
 +The structure returned contains either the information obtained from the name
 +server,
  .Xr named 8 ,
  broken-out fields from a line in
  .Pa /etc/hosts ,
 @@ -198,6 +225,23 @@
  .It Pa /etc/nsswitch.conf
  .It Pa /etc/resolv.conf
  .El
 +.Sh EXAMPLES
 +Print out the hostname associated with a specific IP address:
 +.Pp
 +.Bd -literal
 +	const char *ipstr = "127.0.0.1";
 +	struct in_addr ip;
 +	struct hostent *hp;
 +
 +	if (!inet_aton(ipstr, &ip))
 +		errx(1, "can't parse IP address %s", ipstr);
 +
 +	if ((hp = gethostbyaddr((const char *)&ip,
 +	    sizeof ip, AF_INET)) == NULL)
 +		errx(1, "no name associated with %s", ipstr);
 +
 +	printf("name associated with %s is %s\en", ipstr, hp->h_name);
 +.Ed -literal
  .Sh DIAGNOSTICS
  Error return status from 
  .Fn gethostbyname ,
 @@ -243,6 +287,7 @@
  for example, a mail-forwarder may be registered for this domain.
  .El
  .Sh SEE ALSO
 +.Xr inet_aton 3 ,
  .Xr resolver 3 ,
  .Xr hosts 5 ,
  .Xr hostname 7 ,
 -- 
 Ben Smithurst / ben@FreeBSD.org / PGP: 0x99392F7D
 

From: Ben Smithurst <ben@FreeBSD.org>
To: Joakim Henriksson <murduth@ludd.luth.se>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/24225: Useless gethostbyaddr man page
Date: Wed, 10 Jan 2001 15:41:07 +0000

 Joakim Henriksson wrote:
 
 > The manual page for gethostbyaddr does not even describe what the arguments 
 > should be.
 
      struct hostent *
      gethostbyaddr(const char *addr, int len, int type)
 
 An address, a length, a type.  What more do you want? ;-)
 
 Oh, ok, I might see if I can come up with anything, depends how busy I
 am...
 
 > Steal from linux
 
 Oh.  My.  God.
 
 One thing I like about FreeBSD is its useful manual pages, so I don't
 think copying one from Linux would be a great idea.
 
 -- 
 Ben Smithurst / ben@FreeBSD.org / PGP: 0x99392F7D
 

From: Joakim Henriksson <murduth@ludd.luth.se>
To: Ben Smithurst <ben@FreeBSD.org>
Cc: Joakim Henriksson <murduth@ludd.luth.se>,
	FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/24225: Useless gethostbyaddr man page 
Date: Wed, 10 Jan 2001 20:19:30 +0100

 > > The manual page for gethostbyaddr does not even describe what the arguments 
 > > should be.
 > 
 > ok, what do you (and everyone else) think of this patch?
 
 Visually examining the patch it seems ok. Didn't get it to apply in any sane 
 maner though.
 -- 
 regards/ Joakim
 
 
 
State-Changed-From-To: open->closed 
State-Changed-By: nik 
State-Changed-When: Fri Feb 9 11:06:10 PST 2001 
State-Changed-Why:  
Committed. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=24225 
>Unformatted:
