.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.