getphonenumberbyname.3c

早期freebsd实现

.TH GETPHONENUMBERBYNAME 3C "Feb 14, 1989"
.SH NAME
getphonenumberbyname, getnamebyphonenumber, getphonenumberent, setphonenumberent, endphonenumberent \- get telephone number directory entry
.SH SYNOPSIS
.B "#include <phonenumber.h>
.PP
.B "extern int pn_errno;
.PP
.B "struct phonenumberent *getphonenumberbyname(name)
.br
.B "char *name;
.PP
.B "struct phonenumberent *getnamebyphonenumber(number, type)
.br
.B "char *number; int type;
.PP
.B "struct phonenumberent *getphonenumberent()
.PP
.B "setphonenumberent(stayopen)
.br
.B "int stayopen;
.PP
.B "endphonenumberent()
.PP
.SH DESCRIPTION
.I Getphonenumberbyname
and
.I getnamebyphonenumber
each return a pointer to an object with the
following structure.
This structure contains either the information obtained from the name server,
.IR named (8),
or broken-out fields from a line in 
.IR /etc/phonenumbers .
If the local name server is not running these routines do a lookup in
.IR /etc/phonenumbers .
.RS
.PP
.nf
struct	phonenumberent {
	char	*pn_name;	/* directory listing name */
	char	**pn_aliases;	/* alias list */
	int	pn_length;	/* length of phone number address */
	char	**pn_addr_list;	/* list of addresses from name server */
	struct	pn_addr	*pn_addrtype;	/* list of phone number address types */
};
.ft R
.ad
.fi
.RE
.PP
The members of this structure are:
.TP \w'pn_addr_list'u+2n
pn_name
Official directory listing name of the phone number.
.TP \w'pn_addr_list'u+2n
pn_aliases
A zero terminated array of alternate names for this phone number.
.TP \w'pn_addr_list'u+2n
pn_addrtype
A zero terminated array of address types that can reach this location.
.TP \w'pn_addr_list'u+2n
pn_addr_list
A zero terminated array of phone numbers to reach this location.
.PP
.SH DIAGNOSTICS
.PP
Error return status from 
.I getphonenumberbyname
and
.I getphonenumberbyaddr
is indicated by return of a null pointer.
The external integer
.IR pn_errno
may then be checked to see whether this is a temporary failure
or an invalid or unknown phonenumber.
.PP
.IR pn_errno
can have the following values:
.RS
.IP ENTRY_NOT_FOUND \w'ENTRY_NOT_FOUND'u+2n
No such phonenumber is known.
.IP TRY_AGAIN \w'ENTRY_NOT_FOUND'u+2n
This is usually a temporary error
and means that the local server did not receive
a response from an authoritative server.
A retry at some later time may succeed.
.IP NO_RECOVERY \w'ENTRY_NOT_FOUND'u+2n
This is a non-recoverable error.
.IP NO_ADDRESS \w'ENTRY_NOT_FOUND'u+2n
The requested name is valid but does not have an IP address; 
this is not a temporary error.  
This means another type
of request to the name server will result in an answer.
.RE
.SH FILES
/etc/phonenumbers
.SH "SEE ALSO"
phonenumbers(5), resolver(3), named(8)
.SH CAVEAT
.PP
.I Getphonenumberent
is defined, and
.I setphonenumberent
and
.I endphonenumberent
are redefined,
when
.IR libc
is built to use only the routines to lookup in
.IR /etc/phonenumbers 
and not the name server.
.PP
.I Getphonenumberent
reads the next line of
.IR /etc/phonenumbers ,
opening the file if necessary.
.PP
.I Setphonenumberent 
is redefined to open and rewind the file.  If the
.I stayopen
argument is non-zero,
the phonenumbers data base will not be closed after each call to
.I getphonenumberbyname
or
.IR getphonenumberbyaddr .
.I Endphonenumberent
is redefined to close the file.
.SH BUGS
All information
is contained in a static area
so it must be copied if it is
to be saved.
Multiple address types are not implemented.
Nameserver is not implemented.