Node:Network Databases, Next:, Previous:Network Address Conversion, Up:Networking


38.11.2 Network Databases

This section describes procedures which query various network databases. Care should be taken when using the database routines since they are not reentrant.

38.11.2.1 The Host Database

A host object is a structure that represents what is known about a network host, and is the usual way of representing a system's network identity inside software.

The following functions accept a host object and return a selected component:

hostent:name host Scheme Procedure
The "official" hostname for host.

hostent:aliases host Scheme Procedure
A list of aliases for host.

hostent:addrtype host Scheme Procedure
The host address type. For hosts with Internet addresses, this will return AF_INET.

hostent:length host Scheme Procedure
The length of each address for host, in bytes.

hostent:addr-list host Scheme Procedure
The list of network addresses associated with host.

The following procedures are used to search the host database:

gethost [host] Scheme Procedure
gethostbyname hostname Scheme Procedure
gethostbyaddr address Scheme Procedure
scm_gethost (host) C Function
Look up a host by name or address, returning a host object. The gethost procedure will accept either a string name or an integer address; if given no arguments, it behaves like gethostent (see below). If a name or address is supplied but the address can not be found, an error will be thrown to one of the keys: host-not-found, try-again, no-recovery or no-data, corresponding to the equivalent h_error values. Unusual conditions may result in errors thrown to the system-error or misc_error keys. 
(gethost "www.gnu.org")
=> #("www.gnu.org" () 2 4 (3353880842))

(gethostbyname "www.emacs.org")
=> #("emacs.org" ("www.emacs.org") 2 4 (1073448978))

The following procedures may be used to step through the host database from beginning to end.

sethostent [stayopen] Scheme Procedure
Initialize an internal stream from which host objects may be read. This procedure must be called before any calls to gethostent, and may also be called afterward to reset the host entry stream. If stayopen is supplied and is not #f, the database is not closed by subsequent gethostbyname or gethostbyaddr calls, possibly giving an efficiency gain.

gethostent Scheme Procedure
Return the next host object from the host database, or #f if there are no more hosts to be found (or an error has been encountered). This procedure may not be used before sethostent has been called.

endhostent Scheme Procedure
Close the stream used by gethostent. The return value is unspecified.

sethost [stayopen] Scheme Procedure
scm_sethost (stayopen) C Function
If stayopen is omitted, this is equivalent to endhostent. Otherwise it is equivalent to sethostent stayopen.

38.11.2.2 The Network Database

The following functions accept an object representing a network and return a selected component:

netent:name net Scheme Procedure
The "official" network name.

netent:aliases net Scheme Procedure
A list of aliases for the network.

netent:addrtype net Scheme Procedure
The type of the network number. Currently, this returns only AF_INET.

netent:net net Scheme Procedure
The network number.

The following procedures are used to search the network database:

getnet [net] Scheme Procedure
getnetbyname net-name Scheme Procedure
getnetbyaddr net-number Scheme Procedure
scm_getnet (net) C Function
Look up a network by name or net number in the network database. The net-name argument must be a string, and the net-number argument must be an integer. getnet will accept either type of argument, behaving like getnetent (see below) if no arguments are given.

The following procedures may be used to step through the network database from beginning to end.

setnetent [stayopen] Scheme Procedure
Initialize an internal stream from which network objects may be read. This procedure must be called before any calls to getnetent, and may also be called afterward to reset the net entry stream. If stayopen is supplied and is not #f, the database is not closed by subsequent getnetbyname or getnetbyaddr calls, possibly giving an efficiency gain.

getnetent Scheme Procedure
Return the next entry from the network database.

endnetent Scheme Procedure
Close the stream used by getnetent. The return value is unspecified.

setnet [stayopen] Scheme Procedure
scm_setnet (stayopen) C Function
If stayopen is omitted, this is equivalent to endnetent. Otherwise it is equivalent to setnetent stayopen.

38.11.2.3 The Protocol Database

The following functions accept an object representing a protocol and return a selected component:

protoent:name protocol Scheme Procedure
The "official" protocol name.

protoent:aliases protocol Scheme Procedure
A list of aliases for the protocol.

protoent:proto protocol Scheme Procedure
The protocol number.

The following procedures are used to search the protocol database:

getproto [protocol] Scheme Procedure
getprotobyname name Scheme Procedure
getprotobynumber number Scheme Procedure
scm_getproto (protocol) C Function
Look up a network protocol by name or by number. getprotobyname takes a string argument, and getprotobynumber takes an integer argument. getproto will accept either type, behaving like getprotoent (see below) if no arguments are supplied.

The following procedures may be used to step through the protocol database from beginning to end.

setprotoent [stayopen] Scheme Procedure
Initialize an internal stream from which protocol objects may be read. This procedure must be called before any calls to getprotoent, and may also be called afterward to reset the protocol entry stream. If stayopen is supplied and is not #f, the database is not closed by subsequent getprotobyname or getprotobynumber calls, possibly giving an efficiency gain.

getprotoent Scheme Procedure
Return the next entry from the protocol database.

endprotoent Scheme Procedure
Close the stream used by getprotoent. The return value is unspecified.

setproto [stayopen] Scheme Procedure
scm_setproto (stayopen) C Function
If stayopen is omitted, this is equivalent to endprotoent. Otherwise it is equivalent to setprotoent stayopen.

38.11.2.4 The Service Database

The following functions accept an object representing a service and return a selected component:

servent:name serv Scheme Procedure
The "official" name of the network service.

servent:aliases serv Scheme Procedure
A list of aliases for the network service.

servent:port serv Scheme Procedure
The Internet port used by the service.

servent:proto serv Scheme Procedure
The protocol used by the service. A service may be listed many times in the database under different protocol names.

The following procedures are used to search the service database:

getserv [name [protocol]] Scheme Procedure
getservbyname name protocol Scheme Procedure
getservbyport port protocol Scheme Procedure
scm_getserv (name, protocol) C Function
Look up a network service by name or by service number, and return a network service object. The protocol argument specifies the name of the desired protocol; if the protocol found in the network service database does not match this name, a system error is signalled.

The getserv procedure will take either a service name or number as its first argument; if given no arguments, it behaves like getservent (see below). 

(getserv "imap" "tcp")
=> #("imap2" ("imap") 143 "tcp")

(getservbyport 88 "udp")
=> #("kerberos" ("kerberos5" "krb5") 88 "udp")

The following procedures may be used to step through the service database from beginning to end.

setservent [stayopen] Scheme Procedure
Initialize an internal stream from which service objects may be read. This procedure must be called before any calls to getservent, and may also be called afterward to reset the service entry stream. If stayopen is supplied and is not #f, the database is not closed by subsequent getservbyname or getservbyport calls, possibly giving an efficiency gain.

getservent Scheme Procedure
Return the next entry from the services database.

endservent Scheme Procedure
Close the stream used by getservent. The return value is unspecified.

setserv [stayopen] Scheme Procedure
scm_setserv (stayopen) C Function
If stayopen is omitted, this is equivalent to endservent. Otherwise it is equivalent to setservent stayopen.