ACCEPT(2) Linux Programmer's Manual ACCEPT(2)
NAME
accept - accept a connection on a socket
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
int accept(int s, struct sockaddr *addr, int *addrlen);
DESCRIPTION
The argument s is a socket that has been created with
socket(2), bound to an address with bind(2), and is lis-
tening for connections after a listen(2). The accept
function extracts the first connection request on the
queue of pending connections, creates a new socket with
the same properties of s and allocates a new file descrip-
tor for the socket. If no pending connections are present
on the queue, and the socket is not marked as non-block-
ing, accept blocks the caller until a connection is pre-
sent. If the socket is marked non-blocking and no pending
connections are present on the queue, accept returns an
error as described below. The accepted socket may not be
used to accept more connections. The original socket s
remains open.
The argument addr is a result parameter that is filled in
with the address of the connecting entity, as known to the
communications layer. The exact format of the addr param-
eter is determined by the domain in which the communica-
tion is occurring. The addrlen is a value-result parame-
ter; it should initially contain the amount of space
pointed to by addr; on return it will contain the actual
length (in bytes) of the address returned. This call is
used with connection-based socket types, currently with
SOCK_STREAM.
It is possible to select(2) a socket for the purposes of
doing an accept by selecting it for read.
For certain protocols which require an explicit confirma-
tion, such as ISO or DATAKIT, accept can be thought of as
merely dequeuing the next connection request and not
implying confirmation. Confirmation can be implied by a
normal read or write on the new file descriptor, and
rejection can be implied by closing the new socket.
One can obtain user connection request data without con-
firming the connection by issuing a recvmsg(2) call with
an msg_iovlen of 0 and a non-zero msg_controllen, or by
issuing a getsockopt(2) request. Similarly, one can pro-
vide user connection rejection information by issuing a
sendmsg(2) call with providing only the control informa-
tion, or by calling setsockopt(2).
RETURN VALUES
The call returns -1 on error. If it succeeds, it returns
a non-negative integer that is a descriptor for the
accepted socket.
ERRORS
EBADF The descriptor is invalid.
ENOTSOCK
The descriptor references a file, not a socket.
EOPNOTSUPP
The referenced socket is not of type SOCK_STREAM.
EFAULT The addr parameter is not in a writable part of the
user address space.
EWOULDBLOCK
The socket is marked non-blocking and no connec-
tions are present to be accepted.
CONFORMING TO
SVr4, 4.4BSD (the accept function first appeared in BSD
4.2). SVr4 documents an additional EOPNOTSUPP error con-
dition.
SEE ALSO
bind(2), connect(2), listen(2), select(2), socket(2)
BIND(2) Linux Programmer's Manual BIND(2)
NAME
bind - bind a name to a socket
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
int bind(int sockfd, struct sockaddr *my_addr, int
addrlen);
DESCRIPTION
bind gives the socket, sockfd, the local address my_addr.
my_addr is addrlen bytes long. Traditionally, this is
called "assigning a name to a socket" (when a socket is
created with socket(2), it exists in a name space (address
family) but has no name assigned.)
NOTES
Binding a name in the UNIX domain creates a socket in the
file system that must be deleted by the caller when it is
no longer needed (using unlink(2)).
The rules used in name binding vary between communication
domains. Consult the manual entries in section 4 for
detailed information.
RETURN VALUE
On success, zero is returned. On error, -1 is returned,
and errno is set appropriately.
ERRORS
EBADF sockfd is not a valid descriptor.
EINVAL The socket is already bound to an address. This
may change in the future: see linux/unix/sock.c
for details.
EACCES The address is protected, and the user is not the
super-user.
ENOTSOCK
Argument is a descriptor for a file, not a socket.
The following errors are specific to UNIX domain (AF_UNIX)
sockets:
EINVAL The addr_len was wrong, or the socket was not in
the AF_UNIX family.
EROFS The socket inode would reside on a read-only file
system.
EFAULT my_addr points outside your accessible address
space.
ENAMETOOLONG
my_addr is too long.
ENOENT The file does not exist.
ENOMEM Insufficient kernel memory was available.
ENOTDIR A component of the path prefix is not a directory.
EACCES Search permission is denied on a component of the
path prefix.
ELOOP my_addr contains a circular reference (i.e., via a
symbolic link)
CONFORMING TO
SVr4, 4.4BSD (the bind function first appeared in BSD
4.2). SVr4 documents additional EADDRNOTAVAIL, EADDRI-
NUSE, ENOSR general error conditions, and additional EIO,
EISDIR and EROFS Unix-domain error conditions.
SEE ALSO
accept(2), connect(2), listen(2), socket(2), getsock-
name(2)
CONNECT(2) Linux Programmer's Manual CONNECT(2)
NAME
connect - initiate a connection on a socket
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
int connect(int sockfd, struct sockaddr *serv_addr, int
addrlen );
DESCRIPTION
The parameter sockfd is a socket. If it is of type
SOCK_DGRAM, this call specifies the peer with which the
socket is to be associated; this address is that to which
datagrams are to be sent, and the only address from which
datagrams are to be received. If the socket is of type
SOCK_STREAM , this call attempts to make a connection to
another socket. The other socket is specified by
serv_addr, which is an address in the communications space
of the socket. Each communications space interprets the
serv_addr, parameter in its own way. Generally, stream
sockets may successfully connect only once; datagram sock-
ets may use connect multiple times to change their associ-
ation. Datagram sockets may dissolve the association by
connecting to an invalid address, such as a null address.
RETURN VALUE
If the connection or binding succeeds, zero is returned.
On error, -1 is returned, and errno is set appropriately.
ERRORS
The following are general socket errors only. There may
be other domain-specific error codes.
EBADF Bad descriptor.
EFAULT The socket structure address is outside your
address space.
ENOTSOCK
The descriptor is not associated with a socket.
EISCONN
The socket is already connected.
ECONNREFUSED
Connection refused at server.
ETIMEDOUT
Timeout while attempting connection.
ENETUNREACH
Network is unreachable.
EADDRINUSE
Address is already in use.
EINPROGRESS
The socket is non-blocking and the connection can-
not be completed immediately. It is possible to
select(2) for completion by selecting the socket
for writing. After select indicates writability,
use getsockopt(2) to read the SO_ERROR option at
level SOL_SOCKET to determine whether connect com-
pleted successfully (SO_ERROR is zero) or unsuc-
cessfully (SO_ERROR is one of the usual error codes
listed above, explaining the reason for the fail-
ure).
EALREADY
The socket is non-blocking and a previous connec-
tion attempt has not yet been completed.
CONFORMING TO
SVr4, 4.4BSD (the connect function first appeared in BSD
4.2). SVr4 documents additional general error codes EAD-
DRNOTAVAIL, EINVAL, EAFNOSUPPORT, EALREADY, EINTR, EPROTO-
TYPE, ENOSR. It also documents many additional error con-
ditions not described here.
SEE ALSO
accept(2), bind(2), listen(2), socket(2), getsockname(2)
RESOLVER(3) Linux Programmer's Manual RESOLVER(3)
NAME
res_init, res_query, res_search, res_querydomain,
res_mkquery, res_send, dn_comp, dn_expand - resolver rou-
tines
SYNOPSIS
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>
extern struct state _res;
int res_init(void);
int res_query(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_search(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_querydomain(const char *name, const char *domain,
int class, int type, unsigned char *answer, int anslen);
int res_mkquery(int op, const char *dname, int class, int type,
char *data, int datalen, struct rrec *newrr, char *buf,
int buflen);
int res_send(const char *msg, int msglen, char *answer,
int anslen);
int dn_comp(unsigned char *exp_dn, unsigned char *comp_dn,
int length, unsigned char **dnptrs, unsigned char *exp_dn,
unsigned char **lastdnptr);
int dn_expand(unsigned char *msg, unsigned char *eomorig,
unsigned char *comp_dn, unsigned char *exp_dn, int length);
DESCRIPTION
These functions make queries to and interpret the
responses from Internet domain name servers.
The res_init() function reads the configuration files (see
resolv+(8)) to get the default domain name, search order
and name server address(es). If no server is given, the
local host is tried. If no domain is given, that associ-
ated with the local host is used. It can be overridden
with the environment variable LOCALDOMAIN. res_init() is
normally executed by the first call to one of the other
functions.
The res_query() function queries the name server for the
fully-qualified domain name name of specified type and
class. The reply is left in the buffer answer of length
anslen supplied by the caller.
The res_search() function makes a query and waits for the
response like res_query(), but in addition implements the
default and search rules controlled by RES_DEFNAMES and
RES_DNSRCH (see description of _res options below).
The res_querydomain() function makes a query using
res_query() on the concatenation of name and domain.
The following functions are lower-level routines used by
res_query().
The res_mkquery() function constructs a query message in
buf of length buflen for the domain name dname. The query
type op is usually QUERY, but can be any of the types
defined in <arpa/nameser.h>. newrr is currently unused.
The res_send() function sends a pre-formatted query given
in msg of length msglen and returns the answer in answer
which is of length anslen. It will call res_init(), if it
has not already been called.
The dn_comp() function compresses the domain name exp_dn
and stores it in the buffer comp_dn of length length. The
compression uses an array of pointers dnptrs to previously
compressed names in the current message. The first
pointer points to the beginning of the message and the
list ends with NULL. The limit of the array is specified
by lastdnptr. if dnptr is NULL, domain names are not com-
pressed. If lastdnptr is NULL, the list of labels is not
updated.
The dn_expand() function expands the compressed domain
name comp_dn to a full domain name, which is placed in the
buffer exp_dn of size length. The compressed name is con-
tained in a query or reply message, and msg points to the
beginning of the message.
The resolver routines use global configuration and state
information contained in the structure _res, which is
defined in <resolv.h>. The only field that is normally
manipulated by the user is _res.options. This field can
contain the bitwise ``or'' of the following options:
RES_INIT
True if res_init() has been called.
RES_DEBUG
Print debugging messages.
RES_AAONLY
Accept authoritative answers only. res_send() con-
tinues until it fins an authoritative answer or
returns an error. [Not currently implemented].
RES_USEVC
Use TCP connections for queries rather than UDP
datagrams.
RES_PRIMARY
Query primary domain name server only.
RES_IGNTC
Ignore truncation errors. Don't retry with TCP.
[Not currently implemented].
RES_RECURSE
Set the recursion desired bit in queries. Recur-
sion is carried out by the domain name server, not
by res_send(). [Enabled by default].
RES_DEFNAMES
If set, res_search() will append the default domain
name to single component names, ie. those that do
not contain a dot. [Enabled by default].
RES_STAYOPEN
Used with RES_USEVC to keep the TCP connection open
between queries.
RES_DNSRCH
If set, res_search() will search for host names in
the current domain and in parent domains. This
option is used by gethostbyname(3). [Enabled by
default].
RETURN VALUE
The res_init() function returns 0 on success, or -1 if an
error occurs.
The res_query(), res_search(), res_querydomain(),
res_mkquery() and res_send() functions return the length
of the response, or -1 if an error occurs.
The dn_comp() and dn_expand() functions return the length
of the compressed name, or -1 if an error occurs.
FILES
/etc/resolv.conf resolver configuration file
/etc/host.conf resolver configuration file
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), hostname(7), named(8), resolv+(8)
RESOLVER(3) Linux Programmer's Manual RESOLVER(3)
NAME
res_init, res_query, res_search, res_querydomain,
res_mkquery, res_send, dn_comp, dn_expand - resolver rou-
tines
SYNOPSIS
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>
extern struct state _res;
int res_init(void);
int res_query(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_search(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_querydomain(const char *name, const char *domain,
int class, int type, unsigned char *answer, int anslen);
int res_mkquery(int op, const char *dname, int class, int type,
char *data, int datalen, struct rrec *newrr, char *buf,
int buflen);
int res_send(const char *msg, int msglen, char *answer,
int anslen);
int dn_comp(unsigned char *exp_dn, unsigned char *comp_dn,
int length, unsigned char **dnptrs, unsigned char *exp_dn,
unsigned char **lastdnptr);
int dn_expand(unsigned char *msg, unsigned char *eomorig,
unsigned char *comp_dn, unsigned char *exp_dn, int length);
DESCRIPTION
These functions make queries to and interpret the
responses from Internet domain name servers.
The res_init() function reads the configuration files (see
resolv+(8)) to get the default domain name, search order
and name server address(es). If no server is given, the
local host is tried. If no domain is given, that associ-
ated with the local host is used. It can be overridden
with the environment variable LOCALDOMAIN. res_init() is
normally executed by the first call to one of the other
functions.
The res_query() function queries the name server for the
fully-qualified domain name name of specified type and
class. The reply is left in the buffer answer of length
anslen supplied by the caller.
The res_search() function makes a query and waits for the
response like res_query(), but in addition implements the
default and search rules controlled by RES_DEFNAMES and
RES_DNSRCH (see description of _res options below).
The res_querydomain() function makes a query using
res_query() on the concatenation of name and domain.
The following functions are lower-level routines used by
res_query().
The res_mkquery() function constructs a query message in
buf of length buflen for the domain name dname. The query
type op is usually QUERY, but can be any of the types
defined in <arpa/nameser.h>. newrr is currently unused.
The res_send() function sends a pre-formatted query given
in msg of length msglen and returns the answer in answer
which is of length anslen. It will call res_init(), if it
has not already been called.
The dn_comp() function compresses the domain name exp_dn
and stores it in the buffer comp_dn of length length. The
compression uses an array of pointers dnptrs to previously
compressed names in the current message. The first
pointer points to the beginning of the message and the
list ends with NULL. The limit of the array is specified
by lastdnptr. if dnptr is NULL, domain names are not com-
pressed. If lastdnptr is NULL, the list of labels is not
updated.
The dn_expand() function expands the compressed domain
name comp_dn to a full domain name, which is placed in the
buffer exp_dn of size length. The compressed name is con-
tained in a query or reply message, and msg points to the
beginning of the message.
The resolver routines use global configuration and state
information contained in the structure _res, which is
defined in <resolv.h>. The only field that is normally
manipulated by the user is _res.options. This field can
contain the bitwise ``or'' of the following options:
RES_INIT
True if res_init() has been called.
RES_DEBUG
Print debugging messages.
RES_AAONLY
Accept authoritative answers only. res_send() con-
tinues until it fins an authoritative answer or
returns an error. [Not currently implemented].
RES_USEVC
Use TCP connections for queries rather than UDP
datagrams.
RES_PRIMARY
Query primary domain name server only.
RES_IGNTC
Ignore truncation errors. Don't retry with TCP.
[Not currently implemented].
RES_RECURSE
Set the recursion desired bit in queries. Recur-
sion is carried out by the domain name server, not
by res_send(). [Enabled by default].
RES_DEFNAMES
If set, res_search() will append the default domain
name to single component names, ie. those that do
not contain a dot. [Enabled by default].
RES_STAYOPEN
Used with RES_USEVC to keep the TCP connection open
between queries.
RES_DNSRCH
If set, res_search() will search for host names in
the current domain and in parent domains. This
option is used by gethostbyname(3). [Enabled by
default].
RETURN VALUE
The res_init() function returns 0 on success, or -1 if an
error occurs.
The res_query(), res_search(), res_querydomain(),
res_mkquery() and res_send() functions return the length
of the response, or -1 if an error occurs.
The dn_comp() and dn_expand() functions return the length
of the compressed name, or -1 if an error occurs.
FILES
/etc/resolv.conf resolver configuration file
/etc/host.conf resolver configuration file
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), hostname(7), named(8), resolv+(8)
GETHOSTBYNAME(3) Linux Programmer's Manual GETHOSTBYNAME(3)
NAME
gethostbyname, gethostbyaddr, sethostent, endhostent, her-
ror - get network host entry
SYNOPSIS
#include <netdb.h>
extern int h_errno;
struct hostent *gethostbyname(const char *name);
#include <sys/socket.h> /* for AF_INET */
struct hostent *gethostbyaddr(const char *addr, int len, int type);
void sethostent(int stayopen);
void endhostent(void);
void herror(const char *s);
DESCRIPTION
The gethostbyname() function returns a structure of type
hostent for the given host name. Here name is either a
host name, or an IPv4 address in standard dot notation, or
an IPv6 address in colon (and possibly dot) notation. (See
RFC 1884 for the description of IPv6 addresses.) If name
doesn't end in a dot and the environment variable HOSTAL-
IASES is set, the alias file pointed to by HOSTALIASES
will first be searched for name. (See hostname(7) for the
file format.) The current domain and its parents are
searched unless name ends in a dot.
The gethostbyaddr() function returns a structure of type
hostent for the given host address addr of length len and
address type type. The only valid address type is cur-
rently AF_INET.
The sethostent() function specifies, if stayopen is true
(1), that a connected TCP socket should be used for the
name server queries and that the connection should remain
open during successive queries. Otherwise, name server
queries will use UDP datagrams.
The endhostent() function ends the use of a TCP connection
for name server queries.
The herror() function prints the error message associated
with the current value of h_errno on stderr.
The domain name queries carried out by gethostbyname() and
gethostbyaddr() use a combination of any or all of the
name server named(8), a broken out line from /etc/hosts,
and the Network Information Service (NIS or YP), depending
upon the contents of the order line in /etc/host.conf.
(See resolv+(8)). The default action is to query
named(8), followed by /etc/hosts.
The hostent structure is defined in <netdb.h> as follows:
struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses */
}
#define h_addr h_addr_list[0] /* for backward compatibility */
The members of the hostent structure are:
h_name The official name of the host.
h_aliases
A zero-terminated array of alternative names for
the host.
h_addrtype
The type of address; always AF_INET at present.
h_length
The length of the address in bytes.
h_addr_list
A zero-terminated array of network addresses for
the host in network byte order.
h_addr The first address in h_addr_list for backward com-
patibility.
RETURN VALUE
The gethostbyname() and gethostbyaddr() functions return
the hostent structure or a NULL pointer if an error
occurs. On error, the h_errno variable holds an error
number.
ERRORS
The variable h_errno can have the following values:
HOST_NOT_FOUND
The specified host is unknown.
NO_ADDRESS
The requested name is valid but does not have an IP
address.
NO_RECOVERY
A non-recoverable name server error occurred.
TRY_AGAIN
A temporary error occurred on an authoritative name
server. Try again later.
FILES
/etc/host.conf
resolver configuration file
/etc/hosts
host database file
CONFORMING TO
BSD 4.3
SEE ALSO
resolver(3), hosts(5), hostname(7), resolv+(8), named(8)
GETNETENT(3) Linux Programmer's Manual GETNETENT(3)
NAME
getnetent, getnetbyname, getnetbyaddr, setnetent, endne-
tent - get network entry
SYNOPSIS
#include <netdb.h>
struct netent *getnetent(void);
struct netent *getnetbyname(const char *name);
struct netent *getnetbyaddr(long net, int type);
void setnetent(int stayopen);
void endnetent(void);
DESCRIPTION
The getnetent() function reads the next line from the file
/etc/networks and returns a structure netent containing
the broken out fields from the line. The /etc/networks
file is opened if necessary.
The getnetbyname() function returns a netent structure for
the line from /etc/networks that matches the network name.
The getnetbyaddr() function returns a netent structure for
the line that matches the network number net of type type.
The setnetent() function opens and rewinds the /etc/net-
works file. If stayopen is true (1), then the file will
not be closed between calls to getnetbyname() and getnet-
byaddr().
The endservent() function closes /etc/networks.
The netent structure is defined in <netdb.h> as follows:
struct netent {
char *n_name; /* official network name */
char **n_aliases; /* alias list */
int n_addrtype; /* net address type */
unsigned long int n_net; /* network number */
}
The members of the netent structure are:
n_name The official name of the network.
n_aliases
A zero terminated list of alternative names for the
network.
n_addrtype
The type of the network number; always AF_INET.
n_net The network number in host byte order.
RETURN VALUE
The getnetent(), getnetbyname() and getnetbyaddr() func-
tions return the netent structure, or a NULL pointer if an
error occurs or the end of the file is reached.
FILES
/etc/networks networks database file
CONFORMING TO
BSD 4.3
SEE ALSO
getprotoent(3), getservent(3), networks(5)
GETPROTOENT(3) Linux Programmer's Manual GETPROTOENT(3)
NAME
getprotoent, getprotobyname, getprotobynumber, setpro-
toent, endprotoent - get protocol entry
SYNOPSIS
#include <netdb.h>
struct protoent *getprotoent(void);
struct protoent *getprotobyname(const char *name);
struct protoent *getprotobynumber(int proto);
void setprotoent(int stayopen);
void endprotoent(void);
DESCRIPTION
The getprotoent() function reads the next line from the
file /etc/protocols and returns a structure protoent con-
taining the broken out fields from the line. The
/etc/protocols file is opened if necessary.
The getprotobyname() function returns a protoent structure
for the line from /etc/protocols that matches the protocol
name name.
The getprotobynumber() function returns a protoent struc-
ture for the line that matches the protocol number number.
The setprotoent() function opens and rewinds the /etc/pro-
tocols file. If stayopen is true (1), then the file will
not be closed between calls to getprotobyname() or getpro-
tobynumber().
The endprotoent() function closes /etc/protocols.
The protoent structure is defined in <netdb.h> as follows:
struct protoent {
char *p_name; /* official protocol name */
char **p_aliases; /* alias list */
int p_proto; /* protocol number */
}
The members of the protoent structure are:
p_name The official name of the protocol.
p_aliases
A zero terminated list of alternative names for the
protocol.
p_proto
The protocol number.
RETURN VALUE
The getprotoent(), getprotobyname() and getprotobynumber()
functions return the protoent structure, or a NULL pointer
if an error occurs or the end of the file is reached.
FILES
/etc/protocols
protocol database file
CONFORMING TO
BSD 4.3
SEE ALSO
getservent(3), getnetent(3), protocols(5)
GETSERVENT(3) Linux Programmer's Manual GETSERVENT(3)
NAME
getservent, getservbyname, getservbyport, setservent, end-
servent - get service entry
SYNOPSIS
#include <netdb.h>
struct servent *getservent(void);
struct servent *getservbyname(const char *name, const char *proto);
struct servent *getservbyport(int port, const char *proto);
void setservent(int stayopen);
void endservent(void);
DESCRIPTION
The getservent() function reads the next line from the
file /etc/services and returns a structure servent con-
taining the broken out fields from the line. The
/etc/services file is opened if necessary.
The getservbyname() function returns a servent structure
for the line from /etc/services that matches the service
name using protocol proto.
The getservbyport() function returns a servent structure
for the line that matches the port port given in network
byte order using protocol proto.
The setservent() function opens and rewinds the /etc/ser-
vices file. If stayopen is true (1), then the file will
not be closed between calls to getservbyname() and get-
servbyport().
The endservent() function closes /etc/services.
The servent structure is defined in <netdb.h> as follows:
struct servent {
char *s_name; /* official service name */
char **s_aliases; /* alias list */
int s_port; /* port number */
char *s_proto; /* protocol to use */
}
The members of the servent structure are:
s_name The official name of the service.
s_aliases
A zero terminated list of alternative names for the
service.
s_port The port number for the service given in network
byte order.
s_proto
The name of the protocol to use with this service.
RETURN VALUE
The getservent(), getservbyname() and getservbyport()
functions return the servent structure, or a NULL pointer
if an error occurs or the end of the file is reached.
FILES
/etc/services
services database file
CONFORMING TO
BSD 4.3
SEE ALSO
getprotoent(3), getnetent(3), services(5)
FCNTL(2) Linux Programmer's Manual FCNTL(2)
NAME
fcntl - manipulate file descriptor
SYNOPSIS
#include <unistd.h>
#include <fcntl.h>
int fcntl(int fd, int cmd);
int fcntl(int fd, int cmd, long arg);
DESCRIPTION
fcntl performs one of various miscellaneous operations on
fd. The operation in question is determined by cmd:
F_DUPFD Makes arg be a copy of fd, closing fd first if
necessary.
The same functionality can be more easily
achieved by using dup2(2).
The old and new descriptors may be used inter-
changeably. They share locks, file position
pointers and flags; for example, if the file
position is modified by using lseek on one of the
descriptors, the position is also changed for the
other.
The two descriptors do not share the close-on-
exec flag, however. The close-on-exec flag of
the copy is off, meaning that it will be closed
on exec.
On success, the new descriptor is returned.
F_GETFD Read the close-on-exec flag. If the low-order
bit is 0, the file will remain open across exec,
otherwise it will be closed.
F_SETFD Set the close-on-exec flag to the value specified
by arg (only the least significant bit is used).
F_GETFL Read the descriptor's flags (all flags (as set by
open(2)) are returned).
F_SETFL Set the descriptor's flags to the value specified
by arg. Only O_APPEND and O_NONBLOCK may be set.
The flags are shared between copies (made with
dup etc.) of the same file descriptor.
The flags and their semantics are described in
open(2).
F_GETLK, F_SETLK and F_SETLKW
Manage discretionary file locks. The third argu-
ment arg is a pointer to a struct flock (that may
be overwritten by this call).
F_GETLK Return the flock structure that prevents us from
obtaining the lock, or set the l_type field of
the lock to F_UNLCK if there is no obstruction.
F_SETLK The lock is set (when l_type is F_RDLCK or
F_WRLCK) or cleared (when it is F_UNLCK). If the
lock is held by someone else, this call returns
-1 and sets errno to EACCES or EAGAIN.
F_SETLKW Like F_SETLK, but instead of returning an error
we wait for the lock to be released.
F_GETOWN Get the process ID (or process group) of the
owner of a socket.
Process groups are returned as negative values.
F_SETOWN Set the process or process group that owns a
socket.
For these commands, ownership means receiving
SIGIO or SIGURG signals.
Process groups are specified using negative val-
ues.
RETURN VALUE
The return value depends on the operation:
F_DUPFD The new descriptor.
F_GETFD Value of flag.
F_GETFL Value of flags.
F_GETOWN Value of descriptor owner.
On error, -1 is returned, and errno is set appropriately.
ERRORS
EACCES Operation is prohibited by locks held by other
processes.
EAGAIN Operation is prohibited because the file has been
memory-mapped by another process.
EDEADLK Specified write lock operation would cause a
deadlock.
EBADF fd is not an open file descriptor.
EINVAL For F_DUPFD, arg is negative or is greater than
the maximum allowable value.
EMFILE For F_DUPFD, the process already has the maximum
number of file descriptors open.
ENOLCK Too many segment locks open, lock table is full.
NOTES
The errors returned by dup2 are different from those
returned by F_DUPFD.
CONFORMING TO
SVr4, SVID, POSIX, X/OPEN, BSD 4.3. Only the operations
F_DUPFD, F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK,
F_SETLK and F_SETLKW are specified in POSIX.1; F_GETOWN
and F_SETOWN are BSDisms not supported in SVr4. The flags
legal for F_GETFL/F_SETFL are those supported by open(2)
and vary between these systems; O_APPEND, O_NONBLOCK,
O_RDONLY, and O_RDWR are specified in POSIX.1. SVr4 sup-
ports several other options and flags not documented here.
POSIX.1 documents an additional EINTR condition. SVr4
documents additional EFAULT, EINTR, EIO, ENOLINK and
EOVERFLOW error conditions.
SEE ALSO
dup2(2), open(2), socket(2), flock(2)
GETDOMAINNAME(2) Linux Programmer's Manual GETDOMAINNAME(2)
NAME
getdomainname, setdomainname - get/set domain name
SYNOPSIS
#include <unistd.h>
int getdomainname(char *name, size_t len);
int setdomainname(const char *name, size_t len);
DESCRIPTION
These functions are used to access or to change the domain
name of the current processor.
RETURN VALUE
On success, zero is returned. On error, -1 is returned,
and errno is set appropriately.
ERRORS
EINVAL For getdomainname, name points to NULL or name is
longer than len.
EPERM For setdomainname, the caller was not the supe-
ruser.
EINVAL For setdomainname, len was too long.
CONFORMING TO
POSIX does not specify these calls.
BUGS
getdomainname is not compliant with other implementations,
since they always return len bytes, even if name is
longer. Linux, however, returns EINVAL in this case (as
of DLL 4.4.1 libraries).
NOTES
Under Linux, getdomainname is implemented at the library
level by calling uname(2).
SEE ALSO
gethostname(2), sethostname(2), uname(2)
GETHOSTBYNAME(3) Linux Programmer's Manual GETHOSTBYNAME(3)
NAME
gethostbyname, gethostbyaddr, sethostent, endhostent, her-
ror - get network host entry
SYNOPSIS
#include <netdb.h>
extern int h_errno;
struct hostent *gethostbyname(const char *name);
#include <sys/socket.h> /* for AF_INET */
struct hostent *gethostbyaddr(const char *addr, int len, int type);
void sethostent(int stayopen);
void endhostent(void);
void herror(const char *s);
DESCRIPTION
The gethostbyname() function returns a structure of type
hostent for the given host name. Here name is either a
host name, or an IPv4 address in standard dot notation, or
an IPv6 address in colon (and possibly dot) notation. (See
RFC 1884 for the description of IPv6 addresses.) If name
doesn't end in a dot and the environment variable HOSTAL-
IASES is set, the alias file pointed to by HOSTALIASES
will first be searched for name. (See hostname(7) for the
file format.) The current domain and its parents are
searched unless name ends in a dot.
The gethostbyaddr() function returns a structure of type
hostent for the given host address addr of length len and
address type type. The only valid address type is cur-
rently AF_INET.
The sethostent() function specifies, if stayopen is true
(1), that a connected TCP socket should be used for the
name server queries and that the connection should remain
open during successive queries. Otherwise, name server
queries will use UDP datagrams.
The endhostent() function ends the use of a TCP connection
for name server queries.
The herror() function prints the error message associated
with the current value of h_errno on stderr.
The domain name queries carried out by gethostbyname() and
gethostbyaddr() use a combination of any or all of the
name server named(8), a broken out line from /etc/hosts,
and the Network Information Service (NIS or YP), depending
upon the contents of the order line in /etc/host.conf.
(See resolv+(8)). The default action is to query
named(8), followed by /etc/hosts.
The hostent structure is defined in <netdb.h> as follows:
struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses */
}
#define h_addr h_addr_list[0] /* for backward compatibility */
The members of the hostent structure are:
h_name The official name of the host.
h_aliases
A zero-terminated array of alternative names for
the host.
h_addrtype
The type of address; always AF_INET at present.
h_length
The length of the address in bytes.
h_addr_list
A zero-terminated array of network addresses for
the host in network byte order.
h_addr The first address in h_addr_list for backward com-
patibility.
RETURN VALUE
The gethostbyname() and gethostbyaddr() functions return
the hostent structure or a NULL pointer if an error
occurs. On error, the h_errno variable holds an error
number.
ERRORS
The variable h_errno can have the following values:
HOST_NOT_FOUND
The specified host is unknown.
NO_ADDRESS
The requested name is valid but does not have an IP
address.
NO_RECOVERY
A non-recoverable name server error occurred.
TRY_AGAIN
A temporary error occurred on an authoritative name
server. Try again later.
FILES
/etc/host.conf
resolver configuration file
/etc/hosts
host database file
CONFORMING TO
BSD 4.3
SEE ALSO
resolver(3), hosts(5), hostname(7), resolv+(8), named(8)
GETHOSTBYNAME(3) Linux Programmer's Manual GETHOSTBYNAME(3)
NAME
gethostbyname, gethostbyaddr, sethostent, endhostent, her-
ror - get network host entry
SYNOPSIS
#include <netdb.h>
extern int h_errno;
struct hostent *gethostbyname(const char *name);
#include <sys/socket.h> /* for AF_INET */
struct hostent *gethostbyaddr(const char *addr, int len, int type);
void sethostent(int stayopen);
void endhostent(void);
void herror(const char *s);
DESCRIPTION
The gethostbyname() function returns a structure of type
hostent for the given host name. Here name is either a
host name, or an IPv4 address in standard dot notation, or
an IPv6 address in colon (and possibly dot) notation. (See
RFC 1884 for the description of IPv6 addresses.) If name
doesn't end in a dot and the environment variable HOSTAL-
IASES is set, the alias file pointed to by HOSTALIASES
will first be searched for name. (See hostname(7) for the
file format.) The current domain and its parents are
searched unless name ends in a dot.
The gethostbyaddr() function returns a structure of type
hostent for the given host address addr of length len and
address type type. The only valid address type is cur-
rently AF_INET.
The sethostent() function specifies, if stayopen is true
(1), that a connected TCP socket should be used for the
name server queries and that the connection should remain
open during successive queries. Otherwise, name server
queries will use UDP datagrams.
The endhostent() function ends the use of a TCP connection
for name server queries.
The herror() function prints the error message associated
with the current value of h_errno on stderr.
The domain name queries carried out by gethostbyname() and
gethostbyaddr() use a combination of any or all of the
name server named(8), a broken out line from /etc/hosts,
and the Network Information Service (NIS or YP), depending
upon the contents of the order line in /etc/host.conf.
(See resolv+(8)). The default action is to query
named(8), followed by /etc/hosts.
The hostent structure is defined in <netdb.h> as follows:
struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses */
}
#define h_addr h_addr_list[0] /* for backward compatibility */
The members of the hostent structure are:
h_name The official name of the host.
h_aliases
A zero-terminated array of alternative names for
the host.
h_addrtype
The type of address; always AF_INET at present.
h_length
The length of the address in bytes.
h_addr_list
A zero-terminated array of network addresses for
the host in network byte order.
h_addr The first address in h_addr_list for backward com-
patibility.
RETURN VALUE
The gethostbyname() and gethostbyaddr() functions return
the hostent structure or a NULL pointer if an error
occurs. On error, the h_errno variable holds an error
number.
ERRORS
The variable h_errno can have the following values:
HOST_NOT_FOUND
The specified host is unknown.
NO_ADDRESS
The requested name is valid but does not have an IP
address.
NO_RECOVERY
A non-recoverable name server error occurred.
TRY_AGAIN
A temporary error occurred on an authoritative name
server. Try again later.
FILES
/etc/host.conf
resolver configuration file
/etc/hosts
host database file
CONFORMING TO
BSD 4.3
SEE ALSO
resolver(3), hosts(5), hostname(7), resolv+(8), named(8)
GETHOSTBYNAME(3) Linux Programmer's Manual GETHOSTBYNAME(3)
NAME
gethostbyname, gethostbyaddr, sethostent, endhostent, her-
ror - get network host entry
SYNOPSIS
#include <netdb.h>
extern int h_errno;
struct hostent *gethostbyname(const char *name);
#include <sys/socket.h> /* for AF_INET */
struct hostent *gethostbyaddr(const char *addr, int len, int type);
void sethostent(int stayopen);
void endhostent(void);
void herror(const char *s);
DESCRIPTION
The gethostbyname() function returns a structure of type
hostent for the given host name. Here name is either a
host name, or an IPv4 address in standard dot notation, or
an IPv6 address in colon (and possibly dot) notation. (See
RFC 1884 for the description of IPv6 addresses.) If name
doesn't end in a dot and the environment variable HOSTAL-
IASES is set, the alias file pointed to by HOSTALIASES
will first be searched for name. (See hostname(7) for the
file format.) The current domain and its parents are
searched unless name ends in a dot.
The gethostbyaddr() function returns a structure of type
hostent for the given host address addr of length len and
address type type. The only valid address type is cur-
rently AF_INET.
The sethostent() function specifies, if stayopen is true
(1), that a connected TCP socket should be used for the
name server queries and that the connection should remain
open during successive queries. Otherwise, name server
queries will use UDP datagrams.
The endhostent() function ends the use of a TCP connection
for name server queries.
The herror() function prints the error message associated
with the current value of h_errno on stderr.
The domain name queries carried out by gethostbyname() and
gethostbyaddr() use a combination of any or all of the
name server named(8), a broken out line from /etc/hosts,
and the Network Information Service (NIS or YP), depending
upon the contents of the order line in /etc/host.conf.
(See resolv+(8)). The default action is to query
named(8), followed by /etc/hosts.
The hostent structure is defined in <netdb.h> as follows:
struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses */
}
#define h_addr h_addr_list[0] /* for backward compatibility */
The members of the hostent structure are:
h_name The official name of the host.
h_aliases
A zero-terminated array of alternative names for
the host.
h_addrtype
The type of address; always AF_INET at present.
h_length
The length of the address in bytes.
h_addr_list
A zero-terminated array of network addresses for
the host in network byte order.
h_addr The first address in h_addr_list for backward com-
patibility.
RETURN VALUE
The gethostbyname() and gethostbyaddr() functions return
the hostent structure or a NULL pointer if an error
occurs. On error, the h_errno variable holds an error
number.
ERRORS
The variable h_errno can have the following values:
HOST_NOT_FOUND
The specified host is unknown.
NO_ADDRESS
The requested name is valid but does not have an IP
address.
NO_RECOVERY
A non-recoverable name server error occurred.
TRY_AGAIN
A temporary error occurred on an authoritative name
server. Try again later.
FILES
/etc/host.conf
resolver configuration file
/etc/hosts
host database file
CONFORMING TO
BSD 4.3
SEE ALSO
resolver(3), hosts(5), hostname(7), resolv+(8), named(8)
GETHOSTNAME(2) Linux Programmer's Manual GETHOSTNAME(2)
NAME
gethostname, sethostname - get/set host name
SYNOPSIS
#include <unistd.h>
int gethostname(char *name, size_t len);
int sethostname(const char *name, size_t len);
DESCRIPTION
These functions are used to access or to change the host
name of the current processor.
RETURN VALUE
On success, zero is returned. On error, -1 is returned,
and errno is set appropriately.
ERRORS
EINVAL len is negative or, for sethostname, len is larger
than the maximum allowed size, or, for gethostname
on Linux/i386, len is smaller than the actual size.
EPERM For sethostname, the caller was not the superuser.
EFAULT name is an invalid address.
CONFORMING TO
SVr4, 4.4BSD (this function first appeared in 4.2BSD).
POSIX.1 does not define these functions, but ISO/IEC
9945-1:1990 mentions them in B.4.4.1.
BUGS
Some other implementations of gethostname successfully
return len bytes even if name is longer. Linux/Alpha com-
plies with this behaviour. Linux/i386, however, returns
EINVAL in this case (as of DLL 4.6.27 libraries).
NOTES
Under Linux/Alpha, gethostname is a system call. Under
Linux/i386, gethostname is implemented at the library
level by calling uname(2).
SEE ALSO
getdomainname(2), setdomainname(2), uname(2)
GETNETENT(3) Linux Programmer's Manual GETNETENT(3)
NAME
getnetent, getnetbyname, getnetbyaddr, setnetent, endne-
tent - get network entry
SYNOPSIS
#include <netdb.h>
struct netent *getnetent(void);
struct netent *getnetbyname(const char *name);
struct netent *getnetbyaddr(long net, int type);
void setnetent(int stayopen);
void endnetent(void);
DESCRIPTION
The getnetent() function reads the next line from the file
/etc/networks and returns a structure netent containing
the broken out fields from the line. The /etc/networks
file is opened if necessary.
The getnetbyname() function returns a netent structure for
the line from /etc/networks that matches the network name.
The getnetbyaddr() function returns a netent structure for
the line that matches the network number net of type type.
The setnetent() function opens and rewinds the /etc/net-
works file. If stayopen is true (1), then the file will
not be closed between calls to getnetbyname() and getnet-
byaddr().
The endservent() function closes /etc/networks.
The netent structure is defined in <netdb.h> as follows:
struct netent {
char *n_name; /* official network name */
char **n_aliases; /* alias list */
int n_addrtype; /* net address type */
unsigned long int n_net; /* network number */
}
The members of the netent structure are:
n_name The official name of the network.
n_aliases
A zero terminated list of alternative names for the
network.
n_addrtype
The type of the network number; always AF_INET.
n_net The network number in host byte order.
RETURN VALUE
The getnetent(), getnetbyname() and getnetbyaddr() func-
tions return the netent structure, or a NULL pointer if an
error occurs or the end of the file is reached.
FILES
/etc/networks networks database file
CONFORMING TO
BSD 4.3
SEE ALSO
getprotoent(3), getservent(3), networks(5)
GETNETENT(3) Linux Programmer's Manual GETNETENT(3)
NAME
getnetent, getnetbyname, getnetbyaddr, setnetent, endne-
tent - get network entry
SYNOPSIS
#include <netdb.h>
struct netent *getnetent(void);
struct netent *getnetbyname(const char *name);
struct netent *getnetbyaddr(long net, int type);
void setnetent(int stayopen);
void endnetent(void);
DESCRIPTION
The getnetent() function reads the next line from the file
/etc/networks and returns a structure netent containing
the broken out fields from the line. The /etc/networks
file is opened if necessary.
The getnetbyname() function returns a netent structure for
the line from /etc/networks that matches the network name.
The getnetbyaddr() function returns a netent structure for
the line that matches the network number net of type type.
The setnetent() function opens and rewinds the /etc/net-
works file. If stayopen is true (1), then the file will
not be closed between calls to getnetbyname() and getnet-
byaddr().
The endservent() function closes /etc/networks.
The netent structure is defined in <netdb.h> as follows:
struct netent {
char *n_name; /* official network name */
char **n_aliases; /* alias list */
int n_addrtype; /* net address type */
unsigned long int n_net; /* network number */
}
The members of the netent structure are:
n_name The official name of the network.
n_aliases
A zero terminated list of alternative names for the
network.
n_addrtype
The type of the network number; always AF_INET.
n_net The network number in host byte order.
RETURN VALUE
The getnetent(), getnetbyname() and getnetbyaddr() func-
tions return the netent structure, or a NULL pointer if an
error occurs or the end of the file is reached.
FILES
/etc/networks networks database file
CONFORMING TO
BSD 4.3
SEE ALSO
getprotoent(3), getservent(3), networks(5)
GETNETENT(3) Linux Programmer's Manual GETNETENT(3)
NAME
getnetent, getnetbyname, getnetbyaddr, setnetent, endne-
tent - get network entry
SYNOPSIS
#include <netdb.h>
struct netent *getnetent(void);
struct netent *getnetbyname(const char *name);
struct netent *getnetbyaddr(long net, int type);
void setnetent(int stayopen);
void endnetent(void);
DESCRIPTION
The getnetent() function reads the next line from the file
/etc/networks and returns a structure netent containing
the broken out fields from the line. The /etc/networks
file is opened if necessary.
The getnetbyname() function returns a netent structure for
the line from /etc/networks that matches the network name.
The getnetbyaddr() function returns a netent structure for
the line that matches the network number net of type type.
The setnetent() function opens and rewinds the /etc/net-
works file. If stayopen is true (1), then the file will
not be closed between calls to getnetbyname() and getnet-
byaddr().
The endservent() function closes /etc/networks.
The netent structure is defined in <netdb.h> as follows:
struct netent {
char *n_name; /* official network name */
char **n_aliases; /* alias list */
int n_addrtype; /* net address type */
unsigned long int n_net; /* network number */
}
The members of the netent structure are:
n_name The official name of the network.
n_aliases
A zero terminated list of alternative names for the
network.
n_addrtype
The type of the network number; always AF_INET.
n_net The network number in host byte order.
RETURN VALUE
The getnetent(), getnetbyname() and getnetbyaddr() func-
tions return the netent structure, or a NULL pointer if an
error occurs or the end of the file is reached.
FILES
/etc/networks networks database file
CONFORMING TO
BSD 4.3
SEE ALSO
getprotoent(3), getservent(3), networks(5)
GETPEERNAME(2) Linux Programmer's Manual GETPEERNAME(2)
NAME
getpeername - get name of connected peer
SYNOPSIS
int getpeername(int s, struct sockaddr *name, int *name-
len);
DESCRIPTION
Getpeername returns the name of the peer connected to
socket s. The namelen parameter should be initialized to
indicate the amount of space pointed to by name. On
return it contains the actual size of the name returned
(in bytes). The name is truncated if the buffer provided
is too small.
RETURN VALUE
On success, zero is returned. On error, -1 is returned,
and errno is set appropriately.
ERRORS
EBADF The argument s is not a valid descriptor.
ENOTSOCK
The argument s is a file, not a socket.
ENOTCONN
The socket is not connected.
ENOBUFS Insufficient resources were available in the sys-
tem to perform the operation.
EFAULT The name parameter points to memory not in a valid
part of the process address space.
CONFORMING TO
SVr4, 4.4BSD (the getpeername function call first appeared
in 4.2BSD).
SEE ALSO
accept(2), bind(2), getsockname(2)
GETPROTOENT(3) Linux Programmer's Manual GETPROTOENT(3)
NAME
getprotoent, getprotobyname, getprotobynumber, setpro-
toent, endprotoent - get protocol entry
SYNOPSIS
#include <netdb.h>
struct protoent *getprotoent(void);
struct protoent *getprotobyname(const char *name);
struct protoent *getprotobynumber(int proto);
void setprotoent(int stayopen);
void endprotoent(void);
DESCRIPTION
The getprotoent() function reads the next line from the
file /etc/protocols and returns a structure protoent con-
taining the broken out fields from the line. The
/etc/protocols file is opened if necessary.
The getprotobyname() function returns a protoent structure
for the line from /etc/protocols that matches the protocol
name name.
The getprotobynumber() function returns a protoent struc-
ture for the line that matches the protocol number number.
The setprotoent() function opens and rewinds the /etc/pro-
tocols file. If stayopen is true (1), then the file will
not be closed between calls to getprotobyname() or getpro-
tobynumber().
The endprotoent() function closes /etc/protocols.
The protoent structure is defined in <netdb.h> as follows:
struct protoent {
char *p_name; /* official protocol name */
char **p_aliases; /* alias list */
int p_proto; /* protocol number */
}
The members of the protoent structure are:
p_name The official name of the protocol.
p_aliases
A zero terminated list of alternative names for the
protocol.
p_proto
The protocol number.
RETURN VALUE
The getprotoent(), getprotobyname() and getprotobynumber()
functions return the protoent structure, or a NULL pointer
if an error occurs or the end of the file is reached.
FILES
/etc/protocols
protocol database file
CONFORMING TO
BSD 4.3
SEE ALSO
getservent(3), getnetent(3), protocols(5)
GETPROTOENT(3) Linux Programmer's Manual GETPROTOENT(3)
NAME
getprotoent, getprotobyname, getprotobynumber, setpro-
toent, endprotoent - get protocol entry
SYNOPSIS
#include <netdb.h>
struct protoent *getprotoent(void);
struct protoent *getprotobyname(const char *name);
struct protoent *getprotobynumber(int proto);
void setprotoent(int stayopen);
void endprotoent(void);
DESCRIPTION
The getprotoent() function reads the next line from the
file /etc/protocols and returns a structure protoent con-
taining the broken out fields from the line. The
/etc/protocols file is opened if necessary.
The getprotobyname() function returns a protoent structure
for the line from /etc/protocols that matches the protocol
name name.
The getprotobynumber() function returns a protoent struc-
ture for the line that matches the protocol number number.
The setprotoent() function opens and rewinds the /etc/pro-
tocols file. If stayopen is true (1), then the file will
not be closed between calls to getprotobyname() or getpro-
tobynumber().
The endprotoent() function closes /etc/protocols.
The protoent structure is defined in <netdb.h> as follows:
struct protoent {
char *p_name; /* official protocol name */
char **p_aliases; /* alias list */
int p_proto; /* protocol number */
}
The members of the protoent structure are:
p_name The official name of the protocol.
p_aliases
A zero terminated list of alternative names for the
protocol.
p_proto
The protocol number.
RETURN VALUE
The getprotoent(), getprotobyname() and getprotobynumber()
functions return the protoent structure, or a NULL pointer
if an error occurs or the end of the file is reached.
FILES
/etc/protocols
protocol database file
CONFORMING TO
BSD 4.3
SEE ALSO
getservent(3), getnetent(3), protocols(5)
GETPROTOENT(3) Linux Programmer's Manual GETPROTOENT(3)
NAME
getprotoent, getprotobyname, getprotobynumber, setpro-
toent, endprotoent - get protocol entry
SYNOPSIS
#include <netdb.h>
struct protoent *getprotoent(void);
struct protoent *getprotobyname(const char *name);
struct protoent *getprotobynumber(int proto);
void setprotoent(int stayopen);
void endprotoent(void);
DESCRIPTION
The getprotoent() function reads the next line from the
file /etc/protocols and returns a structure protoent con-
taining the broken out fields from the line. The
/etc/protocols file is opened if necessary.
The getprotobyname() function returns a protoent structure
for the line from /etc/protocols that matches the protocol
name name.
The getprotobynumber() function returns a protoent struc-
ture for the line that matches the protocol number number.
The setprotoent() function opens and rewinds the /etc/pro-
tocols file. If stayopen is true (1), then the file will
not be closed between calls to getprotobyname() or getpro-
tobynumber().
The endprotoent() function closes /etc/protocols.
The protoent structure is defined in <netdb.h> as follows:
struct protoent {
char *p_name; /* official protocol name */
char **p_aliases; /* alias list */
int p_proto; /* protocol number */
}
The members of the protoent structure are:
p_name The official name of the protocol.
p_aliases
A zero terminated list of alternative names for the
protocol.
p_proto
The protocol number.
RETURN VALUE
The getprotoent(), getprotobyname() and getprotobynumber()
functions return the protoent structure, or a NULL pointer
if an error occurs or the end of the file is reached.
FILES
/etc/protocols
protocol database file
CONFORMING TO
BSD 4.3
SEE ALSO
getservent(3), getnetent(3), protocols(5)
GETSERVENT(3) Linux Programmer's Manual GETSERVENT(3)
NAME
getservent, getservbyname, getservbyport, setservent, end-
servent - get service entry
SYNOPSIS
#include <netdb.h>
struct servent *getservent(void);
struct servent *getservbyname(const char *name, const char *proto);
struct servent *getservbyport(int port, const char *proto);
void setservent(int stayopen);
void endservent(void);
DESCRIPTION
The getservent() function reads the next line from the
file /etc/services and returns a structure servent con-
taining the broken out fields from the line. The
/etc/services file is opened if necessary.
The getservbyname() function returns a servent structure
for the line from /etc/services that matches the service
name using protocol proto.
The getservbyport() function returns a servent structure
for the line that matches the port port given in network
byte order using protocol proto.
The setservent() function opens and rewinds the /etc/ser-
vices file. If stayopen is true (1), then the file will
not be closed between calls to getservbyname() and get-
servbyport().
The endservent() function closes /etc/services.
The servent structure is defined in <netdb.h> as follows:
struct servent {
char *s_name; /* official service name */
char **s_aliases; /* alias list */
int s_port; /* port number */
char *s_proto; /* protocol to use */
}
The members of the servent structure are:
s_name The official name of the service.
s_aliases
A zero terminated list of alternative names for the
service.
s_port The port number for the service given in network
byte order.
s_proto
The name of the protocol to use with this service.
RETURN VALUE
The getservent(), getservbyname() and getservbyport()
functions return the servent structure, or a NULL pointer
if an error occurs or the end of the file is reached.
FILES
/etc/services
services database file
CONFORMING TO
BSD 4.3
SEE ALSO
getprotoent(3), getnetent(3), services(5)
GETSERVENT(3) Linux Programmer's Manual GETSERVENT(3)
NAME
getservent, getservbyname, getservbyport, setservent, end-
servent - get service entry
SYNOPSIS
#include <netdb.h>
struct servent *getservent(void);
struct servent *getservbyname(const char *name, const char *proto);
struct servent *getservbyport(int port, const char *proto);
void setservent(int stayopen);
void endservent(void);
DESCRIPTION
The getservent() function reads the next line from the
file /etc/services and returns a structure servent con-
taining the broken out fields from the line. The
/etc/services file is opened if necessary.
The getservbyname() function returns a servent structure
for the line from /etc/services that matches the service
name using protocol proto.
The getservbyport() function returns a servent structure
for the line that matches the port port given in network
byte order using protocol proto.
The setservent() function opens and rewinds the /etc/ser-
vices file. If stayopen is true (1), then the file will
not be closed between calls to getservbyname() and get-
servbyport().
The endservent() function closes /etc/services.
The servent structure is defined in <netdb.h> as follows:
struct servent {
char *s_name; /* official service name */
char **s_aliases; /* alias list */
int s_port; /* port number */
char *s_proto; /* protocol to use */
}
The members of the servent structure are:
s_name The official name of the service.
s_aliases
A zero terminated list of alternative names for the
service.
s_port The port number for the service given in network
byte order.
s_proto
The name of the protocol to use with this service.
RETURN VALUE
The getservent(), getservbyname() and getservbyport()
functions return the servent structure, or a NULL pointer
if an error occurs or the end of the file is reached.
FILES
/etc/services
services database file
CONFORMING TO
BSD 4.3
SEE ALSO
getprotoent(3), getnetent(3), services(5)
GETSERVENT(3) Linux Programmer's Manual GETSERVENT(3)
NAME
getservent, getservbyname, getservbyport, setservent, end-
servent - get service entry
SYNOPSIS
#include <netdb.h>
struct servent *getservent(void);
struct servent *getservbyname(const char *name, const char *proto);
struct servent *getservbyport(int port, const char *proto);
void setservent(int stayopen);
void endservent(void);
DESCRIPTION
The getservent() function reads the next line from the
file /etc/services and returns a structure servent con-
taining the broken out fields from the line. The
/etc/services file is opened if necessary.
The getservbyname() function returns a servent structure
for the line from /etc/services that matches the service
name using protocol proto.
The getservbyport() function returns a servent structure
for the line that matches the port port given in network
byte order using protocol proto.
The setservent() function opens and rewinds the /etc/ser-
vices file. If stayopen is true (1), then the file will
not be closed between calls to getservbyname() and get-
servbyport().
The endservent() function closes /etc/services.
The servent structure is defined in <netdb.h> as follows:
struct servent {
char *s_name; /* official service name */
char **s_aliases; /* alias list */
int s_port; /* port number */
char *s_proto; /* protocol to use */
}
The members of the servent structure are:
s_name The official name of the service.
s_aliases
A zero terminated list of alternative names for the
service.
s_port The port number for the service given in network
byte order.
s_proto
The name of the protocol to use with this service.
RETURN VALUE
The getservent(), getservbyname() and getservbyport()
functions return the servent structure, or a NULL pointer
if an error occurs or the end of the file is reached.
FILES
/etc/services
services database file
CONFORMING TO
BSD 4.3
SEE ALSO
getprotoent(3), getnetent(3), services(5)
GETSOCKNAME(2) Linux Programmer's Manual GETSOCKNAME(2)
NAME
getsockname - get socket name
SYNOPSIS
int getsockname(int s , struct sockaddr * name , int *
namelen )
DESCRIPTION
Getsockname returns the current name for the specified
socket. The namelen parameter should be initialized to
indicate the amount of space pointed to by name. On
return it contains the actual size of the name returned
(in bytes).
RETURN VALUE
On success, zero is returned. On error, -1 is returned,
and errno is set appropriately. A 0 is returned if the
call succeeds, -1 if it fails.
ERRORS
EBADF The argument s is not a valid descriptor.
ENOTSOCK
The argument s is a file, not a socket.
ENOBUFS Insufficient resources were available in the sys-
tem to perform the operation.
EFAULT The name parameter points to memory not in a valid
part of the process address space.
CONFORMING TO
SVr4, 4.4BSD (the getsockname function call appeared in
4.2BSD). SVr4 documents additional ENOMEM and ENOSR error
codes.
SEE ALSO
bind(2), socket(2)
GETSOCKOPT(2) Linux Programmer's Manual GETSOCKOPT(2)
NAME
getsockopt, setsockopt - get and set options on sockets
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
int getsockopt(int s, int level, int optname, void *opt-
val, int *optlen);
int setsockopt(int s, int level, int optname, const void
*optval, int optlen);
DESCRIPTION
Getsockopt and setsockopt manipulate the options associ-
ated with a socket. Options may exist at multiple proto-
col levels; they are always present at the uppermost
socket level.
When manipulating socket options the level at which the
option resides and the name of the option must be speci-
fied. To manipulate options at the socket level, level is
specified as SOL_SOCKET. To manipulate options at any
other level the protocol number of the appropriate proto-
col controlling the option is supplied. For example, to
indicate that an option is to be interpreted by the TCP
protocol, level should be set to the protocol number of
TCP; see getprotoent(3).
The parameters optval and optlen are used to access option
values for setsockopt. For getsockopt they identify a
buffer in which the value for the requested option(s) are
to be returned. For getsockopt, optlen is a value-result
parameter, initially containing the size of the buffer
pointed to by optval, and modified on return to indicate
the actual size of the value returned. If no option value
is to be supplied or returned, optval may be NULL.
Optname and any specified options are passed uninterpreted
to the appropriate protocol module for interpretation.
The include file <sys/socket.h> contains definitions for
socket level options, described below. Options at other
protocol levels vary in format and name; consult the
appropriate entries in section 4 of the manual.
Most socket-level options utilize an int parameter for
optval. For setsockopt, the parameter should be non-zero
to enable a boolean option, or zero if the option is to be
disabled. SO_LINGER uses a struct linger parameter,
defined in <linux/socket.h>, which specifies the desired
state of the option and the linger interval (see below).
SO_SNDTIMEO and SO_RCVTIMEO use a struct timeval parame-
ter, defined in <sys/time.h>.
The following options are recognized at the socket level.
Except as noted, each may be examined with getsockopt and
set with setsockopt.
SO_DEBUG
enables recording of debugging information
SO_REUSEADDR
enables local address reuse
SO_KEEPALIVE
enables keep connections alive
SO_DONTROUTE
enables routing bypass for outgoing messages
SO_LINGER
linger on close if data present
SO_BROADCAST
enables permission to transmit broadcast messages
SO_OOBINLINE
enables reception of out-of-band data in band
SO_SNDBUF
set buffer size for output
SO_RCVBUF
set buffer size for input
SO_SNDLOWAT
set minimum count for output
SO_RCVLOWAT
set minimum count for input
SO_SNDTIMEO
get timeout value for output (get only)
SO_RCVTIMEO
get timeout value for input (get only)
SO_TYPE get the type of the socket (get only)
SO_ERROR
get and clear error on the socket (get only)
SO_DEBUG enables debugging in the underlying protocol mod-
ules. SO_REUSEADDR indicates that the rules used in vali-
dating addresses supplied in a bind(2) call should allow
reuse of local addresses. SO_KEEPALIVE enables the peri-
odic transmission of messages on a connected socket.
Should the connected party fail to respond to these
messages, the connection is considered broken and pro-
cesses using the socket are notified via a SIGPIPE signal
when attempting to send data. SO_DONTROUTE indicates that
outgoing messages should bypass the standard routing
facilities. Instead, messages are directed to the appro-
priate network interface according to the network portion
of the destination address.
SO_LINGER controls the action taken when unsent messages
are queued on socket and a close(2) is performed. If the
socket promises reliable delivery of data and SO_LINGER is
set, the system will block the process on the close
attempt until it is able to transmit the data or until it
decides it is unable to deliver the information (a timeout
period, termed the linger interval, is specified in the
setsockopt call when SO_LINGER is requested). If
SO_LINGER is disabled and a close is issued, the system
will process the close in a manner that allows the process
to continue as quickly as possible.
The linger structure is defined in <linux/socket.h> as
follows:
struct linger {
int l_onoff; /* Linger active */
int l_linger; /* How long to linger for */
};
l_onoff indicates wether to linger or not. If it is set to
1 then l_linger contains the time in hundredths of seconds
how long the process should linger to complete the close.
If l_onoff is set to zero the process returns immediately.
The option SO_BROADCAST requests permission to send broad-
cast datagrams on the socket. Broadcast was a privileged
operation in earlier versions of the system. With proto-
cols that support out-of-band data, the SO_OOBINLINE
option requests that out-of-band data be placed in the
normal data input queue as received; it will then be
accessible with recv or read calls without the MSG_OOB
flag. Some protocols always behave as if this option is
set. SO_SNDBUF and SO_RCVBUF are options to adjust the
normal buffer sizes allocated for output and input
buffers, respectively. The buffer size may be increased
for high-volume connections, or may be decreased to limit
the possible backlog of incoming data. The system places
an absolute limit on these values.
SO_SNDLOWAT is an option to set the minimum count for out-
put operations. Most output operations process all of the
data supplied by the call, delivering data to the protocol
for transmission and blocking as necessary for flow con-
trol. Nonblocking output operations will process as much
data as permitted subject to flow control without
blocking, but will process no data if flow control does
not allow the smaller of the low water mark value or the
entire request to be processed. A select(2) operation
testing the ability to write to a socket will return true
only if the low water mark amount could be processed. The
default value for SO_SNDLOWAT is set to a convenient size
for network efficiency, often 1024.
SO_RCVLOWAT is an option to set the minimum count for
input operations. In general, receive calls will block
until any (non-zero) amount of data is received, then
return with smaller of the amount available or the amount
requested. The default value for SO_RCVLOWAT is 1. If
SO_RCVLOWAT is set to a larger value, blocking receive
calls normally wait until they have received the smaller
of the low water mark value or the requested amount.
Receive calls may still return less than the low water
mark if an error occurs, a signal is caught, or the type
of data next in the receive queue is different than that
returned.
SO_SNDTIMEO is an option to get the timeout value for out-
put operations. (It can be used with getsockopt only).
It returns a struct timeval parameter with the number of
seconds and microseconds used to limit waits for output
operations to complete. If a send operation has blocked
for this much time, it returns with a partial count or
with the error EWOULDBLOCK if no data were sent. In the
current implementation, this timer is restarted each time
additional data are delivered to the protocol, implying
that the limit applies to output portions ranging in size
from the low water mark to the high water mark for output.
SO_RCVTIMEO is an option to get the timeout value for
input operations. (It can be used with getsockopt only).
It returns a struct timeval parameter with the number of
seconds and microseconds used to limit waits for input
operations to complete. In the current implementation,
this timer is restarted each time additional data are
received by the protocol, and thus the limit is in effect
an inactivity timer. If a receive operation has been
blocked for this much time without receiving additional
data, it returns with a short count or with the error
EWOULDBLOCK if no data were received.
Finally, also SO_TYPE and SO_ERROR are options used only
with getsockopt. SO_TYPE returns the type of the socket,
such as SOCK_STREAM; it is useful for servers that inherit
sockets on startup. SO_ERROR returns any pending error on
the socket and clears the error status. It may be used to
check for asynchronous errors on connected datagram sock-
ets or for other asynchronous errors.
RETURN VALUE
On success, zero is returned. On error, -1 is returned,
and errno is set appropriately.
ERRORS
EBADF The argument s is not a valid descriptor.
ENOTSOCK
The argument s is a file, not a socket.
ENOPROTOOPT
The option is unknown at the level indicated.
EFAULT The address pointed to by optval is not in a valid
part of the process address space. For getsock-
opt, this error may also be returned if optlen is
not in a valid part of the process address space.
CONFORMING TO
SVr4, 4.4BSD (these system calls first appeared in
4.2BSD). SVr4 documents additional ENOMEM and ENOSR error
codes, but does not document the SO_SNDLOWAT, SO_RCVLOWAT,
SO_SNDTIMEO, SO_RCVTIMEO options
BUGS
Several of the socket options should be handled at lower
levels of the system.
SEE ALSO
ioctl(2), socket(2), getprotoent(3), protocols(5)
GETHOSTBYNAME(3) Linux Programmer's Manual GETHOSTBYNAME(3)
NAME
gethostbyname, gethostbyaddr, sethostent, endhostent, her-
ror - get network host entry
SYNOPSIS
#include <netdb.h>
extern int h_errno;
struct hostent *gethostbyname(const char *name);
#include <sys/socket.h> /* for AF_INET */
struct hostent *gethostbyaddr(const char *addr, int len, int type);
void sethostent(int stayopen);
void endhostent(void);
void herror(const char *s);
DESCRIPTION
The gethostbyname() function returns a structure of type
hostent for the given host name. Here name is either a
host name, or an IPv4 address in standard dot notation, or
an IPv6 address in colon (and possibly dot) notation. (See
RFC 1884 for the description of IPv6 addresses.) If name
doesn't end in a dot and the environment variable HOSTAL-
IASES is set, the alias file pointed to by HOSTALIASES
will first be searched for name. (See hostname(7) for the
file format.) The current domain and its parents are
searched unless name ends in a dot.
The gethostbyaddr() function returns a structure of type
hostent for the given host address addr of length len and
address type type. The only valid address type is cur-
rently AF_INET.
The sethostent() function specifies, if stayopen is true
(1), that a connected TCP socket should be used for the
name server queries and that the connection should remain
open during successive queries. Otherwise, name server
queries will use UDP datagrams.
The endhostent() function ends the use of a TCP connection
for name server queries.
The herror() function prints the error message associated
with the current value of h_errno on stderr.
The domain name queries carried out by gethostbyname() and
gethostbyaddr() use a combination of any or all of the
name server named(8), a broken out line from /etc/hosts,
and the Network Information Service (NIS or YP), depending
upon the contents of the order line in /etc/host.conf.
(See resolv+(8)). The default action is to query
named(8), followed by /etc/hosts.
The hostent structure is defined in <netdb.h> as follows:
struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses */
}
#define h_addr h_addr_list[0] /* for backward compatibility */
The members of the hostent structure are:
h_name The official name of the host.
h_aliases
A zero-terminated array of alternative names for
the host.
h_addrtype
The type of address; always AF_INET at present.
h_length
The length of the address in bytes.
h_addr_list
A zero-terminated array of network addresses for
the host in network byte order.
h_addr The first address in h_addr_list for backward com-
patibility.
RETURN VALUE
The gethostbyname() and gethostbyaddr() functions return
the hostent structure or a NULL pointer if an error
occurs. On error, the h_errno variable holds an error
number.
ERRORS
The variable h_errno can have the following values:
HOST_NOT_FOUND
The specified host is unknown.
NO_ADDRESS
The requested name is valid but does not have an IP
address.
NO_RECOVERY
A non-recoverable name server error occurred.
TRY_AGAIN
A temporary error occurred on an authoritative name
server. Try again later.
FILES
/etc/host.conf
resolver configuration file
/etc/hosts
host database file
CONFORMING TO
BSD 4.3
SEE ALSO
resolver(3), hosts(5), hostname(7), resolv+(8), named(8)
HOST.CONF(5) libsocket Reference HOST.CONF(5)
NAME
host.conf - configures the order of name resolving
DESCRIPTION
This file tells the networking libraries which name
resolving resources to use, and in what order.
Valid sources are hosts, bind and nis. hosts refers to
the file hosts, which contains name to IP address map-
pings. bind refers to DNS servers, which are configured
elsewhere (resolv.conf - see resolver(5)). nis refers to
Network Information Services, which probably won't be very
common in a Windows environment, but might be present if
Unix hosts are used.
If you have DNS servers, the recommended order is bind
then hosts, i.e.
order bind, hosts
If you don't have a DNS server, then only hosts is
required, like so:
order hosts
If you specify bind as well as hosts without a DNS server,
then programs are likely to stall when resolving names.
FILES
/etc/host.conf (Linux), C:\WINDOWS\HOST.CONF (Windows)
SEE ALSO
hosts(5), resolver(5)
HOST.CONF(5) libsocket Reference HOST.CONF(5)
NAME
host.conf - configures the order of name resolving
DESCRIPTION
This file tells the networking libraries which name
resolving resources to use, and in what order.
Valid sources are hosts, bind and nis. hosts refers to
the file hosts, which contains name to IP address map-
pings. bind refers to DNS servers, which are configured
elsewhere (resolv.conf - see resolver(5)). nis refers to
Network Information Services, which probably won't be very
common in a Windows environment, but might be present if
Unix hosts are used.
If you have DNS servers, the recommended order is bind
then hosts, i.e.
order bind, hosts
If you don't have a DNS server, then only hosts is
required, like so:
order hosts
If you specify bind as well as hosts without a DNS server,
then programs are likely to stall when resolving names.
FILES
/etc/host.conf (Linux), C:\WINDOWS\HOST.CONF (Windows)
SEE ALSO
hosts(5), resolver(5)
HOSTNAME(7) HOSTNAME(7)
NAME
hostname - host name resolution description
DESCRIPTION
Hostnames are domains. A domain is a hierarchical, dot-
separated list of subdomains. For example, the machine
monet, in the Berkeley subdomain of the EDU subdomain of
the Internet Domain Name System would be represented as
monet.Berkeley.EDU
(with no trailing dot).
Hostnames are often used with network client and server
programs, which must generally translate the name to an
address for use. (This task is usually performed by the
library routine gethostbyname(3).) The default method for
resolving hostnames by the Internet name resolver is to
follow RFC 1535's security recommendations. Actions can
be taken by the administrator to override these recommen-
dations and to have the resolver behave the same as ear-
lier, non-RFC 1535 resolvers.
The default method (using RFC 1535 guidelines) follows:
If the name consists of a single component, i.e. contains
no dot, and if the environment variable ``HOSTALIASES'' is
set to the name of a file, that file is searched for a
string matching the input hostname. The file should con-
sist of lines made up of two strings separated by white-
space, the first of which is the hostname alias, and the
second of which is the complete hostname to be substituted
for that alias. If a case-insensitive match is found
between the hostname to be resolved and the first field of
a line in the file, the substituted name is looked up with
no further processing.
If there is at least one dot in the name, then the name is
first tried as is. The number of dots to cause this
action is configurable by setting the threshold using the
``ndots'' option in /etc/resolv.conf (default: 1). If the
name ends with a dot, the trailing dot is removed, and the
remaining name is looked up (regardless of the setting of
the 'ndots' option) and no further processing is done.
If the input name does not end with a trailing dot, it is
looked up by searching through a list of domains until a
match is found. If neither the search option in the
/etc/resolv.conf file or the ``LOCALDOMAIN'' environment
variable is used, then the search list of domains contains
only the full domain specified by the domain option (in
/etc/resolv.conf) or the domain used in the local hostname
(see hostname(1) and resolver(5)). For example, if the
``domain'' option is set to CS.Berkeley.EDU, then only
CS.Berkeley.EDU will be in the search list and will be the
only domain appended to the partial hostname, for example,
``lithium'', making lithium.CS.Berkeley.EDU the only name
to be tried using the search list.
If the search option is used in /etc/resolv.conf or the
environment variable, ``LOCALDOMAIN'' is set by the user,
then the search list will include what is set by these
methods. For example, if the ``search'' option contained
CS.Berkeley.EDU CChem.Berkeley.EDU Berkeley.EDU
then the partial hostname (e.g., ``lithium'') will be
tried with each domainname appended (in the same order
specified). The resulting hostnames that would be tried
are:
lithium.CS.Berkeley.EDU
lithium.CChem.Berkeley.EDU
lithium.Berkeley.EDU
The environment variable ``LOCALDOMAIN'' overrides the
``search'' and ``domain'' options, and if both search and
domain options are present in the resolver configuration
file, then only the last one listed is used (see
resolver(5)).
If the name was not previously tried ``as is'' (i.e., it
fell below the ``ndots'' threshold or did not contain a
dot), then the name as originally provided is attempted.
SEE ALSO
gethostbyname(3), resolver(5), mailaddr(7), named(8)
HOSTS(5) libsocket Reference HOSTS(5)
NAME
hosts - the host name to IP address mapping file
DESCRIPTION
This file tells the host name resolver the IP address cor-
responding to each host name. This is useful if there is
no DNS server on the network. It can also be used if the
DNS server does not have a record for a particular host
name, but its IP address is known.
The file is a plain ASCII file. Comments are denoted by a
hash at the start of a line. Each line has the following
format:
<IP address> <host name> <alias>
e.g.
# hosts - host name to IP address translation file
127.0.0.1 localhost
192.168.0.2 gertrude
192.168.0.3 herbert
192.168.0.4 norman
192.168.0.5 jonathon jon
There should always be a line refering to localhost. This
is the local computer, and is always accessible.
Note: Windows doesn't use the aliases, so you will need
multiple lines for the same IP address to fake aliasing.
FILES
/etc/hosts (Linux), C:\WINDOWS\HOSTS (Windows)
SEE ALSO
networks(5)
INET(3) Linux Programmer's Manual INET(3)
NAME
inet_aton, inet_addr, inet_network, inet_ntoa,
inet_makeaddr, inet_lnaof, inet_netof - Internet address
manipulation routines
SYNOPSIS
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
int inet_aton(const char *cp, struct in_addr *inp);
unsigned long int inet_addr(const char *cp);
unsigned long int inet_network(const char *cp);
char *inet_ntoa(struct in_addr in);
struct in_addr inet_makeaddr(int net, int host);
unsigned long int inet_lnaof(struct in_addr in);
unsigned long int inet_netof(struct in_addr in);
DESCRIPTION
inet_aton() converts the Internet host address cp from the
standard numbers-and-dots notation into binary data and
stores it in the structure that inp points to. inet_aton
returns nonzero if the address is valid, zero if not.
The inet_addr() function converts the Internet host
address cp from numbers-and-dots notation into binary data
in network byte order. If the input is invalid, -1 is
returned. This is an obsolete interface to inet_aton,
described immediately above; it is obsolete because -1 is
a valid address (255.255.255.255), and inet_aton provides
a cleaner way to indicate error return.
The inet_network() function extracts the network number in
network byte order from the address cp in numbers-and-dots
notation. If the input is invalid, -1 is returned.
The inet_ntoa() function converts the Internet host
address in given in network byte order to a string in
standard numbers-and-dots notation. The string is
returned in a statically allocated buffer, which subse-
quent calls will overwrite.
The inet_makeaddr() function makes an Internet host
address in network byte order by combining the network
number net with the local address host in network net,
both in local host byte order.
The inet_lnaof() function returns the local host address
part of the Internet address in. The local host address
is returned in local host byte order.
The inet_netof() function returns the network number part
of the Internet Address in. The network number is
returned in local host byte order.
The structure in_addr as used in inet_ntoa(),
inet_makeaddr(), inet_lnoaf() and inet_netof() is defined
in netinet/in.h as:
struct in_addr {
unsigned long int s_addr;
}
Note that on the i80x86 the host byte order is Least Sig-
nificant Byte first, whereas the network byte order, as
used on the Internet, is Most Significant Byte first.
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), getnetent(3), hosts(5), networks(5)
INET(3) Linux Programmer's Manual INET(3)
NAME
inet_aton, inet_addr, inet_network, inet_ntoa,
inet_makeaddr, inet_lnaof, inet_netof - Internet address
manipulation routines
SYNOPSIS
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
int inet_aton(const char *cp, struct in_addr *inp);
unsigned long int inet_addr(const char *cp);
unsigned long int inet_network(const char *cp);
char *inet_ntoa(struct in_addr in);
struct in_addr inet_makeaddr(int net, int host);
unsigned long int inet_lnaof(struct in_addr in);
unsigned long int inet_netof(struct in_addr in);
DESCRIPTION
inet_aton() converts the Internet host address cp from the
standard numbers-and-dots notation into binary data and
stores it in the structure that inp points to. inet_aton
returns nonzero if the address is valid, zero if not.
The inet_addr() function converts the Internet host
address cp from numbers-and-dots notation into binary data
in network byte order. If the input is invalid, -1 is
returned. This is an obsolete interface to inet_aton,
described immediately above; it is obsolete because -1 is
a valid address (255.255.255.255), and inet_aton provides
a cleaner way to indicate error return.
The inet_network() function extracts the network number in
network byte order from the address cp in numbers-and-dots
notation. If the input is invalid, -1 is returned.
The inet_ntoa() function converts the Internet host
address in given in network byte order to a string in
standard numbers-and-dots notation. The string is
returned in a statically allocated buffer, which subse-
quent calls will overwrite.
The inet_makeaddr() function makes an Internet host
address in network byte order by combining the network
number net with the local address host in network net,
both in local host byte order.
The inet_lnaof() function returns the local host address
part of the Internet address in. The local host address
is returned in local host byte order.
The inet_netof() function returns the network number part
of the Internet Address in. The network number is
returned in local host byte order.
The structure in_addr as used in inet_ntoa(),
inet_makeaddr(), inet_lnoaf() and inet_netof() is defined
in netinet/in.h as:
struct in_addr {
unsigned long int s_addr;
}
Note that on the i80x86 the host byte order is Least Sig-
nificant Byte first, whereas the network byte order, as
used on the Internet, is Most Significant Byte first.
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), getnetent(3), hosts(5), networks(5)
INET(3) Linux Programmer's Manual INET(3)
NAME
inet_aton, inet_addr, inet_network, inet_ntoa,
inet_makeaddr, inet_lnaof, inet_netof - Internet address
manipulation routines
SYNOPSIS
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
int inet_aton(const char *cp, struct in_addr *inp);
unsigned long int inet_addr(const char *cp);
unsigned long int inet_network(const char *cp);
char *inet_ntoa(struct in_addr in);
struct in_addr inet_makeaddr(int net, int host);
unsigned long int inet_lnaof(struct in_addr in);
unsigned long int inet_netof(struct in_addr in);
DESCRIPTION
inet_aton() converts the Internet host address cp from the
standard numbers-and-dots notation into binary data and
stores it in the structure that inp points to. inet_aton
returns nonzero if the address is valid, zero if not.
The inet_addr() function converts the Internet host
address cp from numbers-and-dots notation into binary data
in network byte order. If the input is invalid, -1 is
returned. This is an obsolete interface to inet_aton,
described immediately above; it is obsolete because -1 is
a valid address (255.255.255.255), and inet_aton provides
a cleaner way to indicate error return.
The inet_network() function extracts the network number in
network byte order from the address cp in numbers-and-dots
notation. If the input is invalid, -1 is returned.
The inet_ntoa() function converts the Internet host
address in given in network byte order to a string in
standard numbers-and-dots notation. The string is
returned in a statically allocated buffer, which subse-
quent calls will overwrite.
The inet_makeaddr() function makes an Internet host
address in network byte order by combining the network
number net with the local address host in network net,
both in local host byte order.
The inet_lnaof() function returns the local host address
part of the Internet address in. The local host address
is returned in local host byte order.
The inet_netof() function returns the network number part
of the Internet Address in. The network number is
returned in local host byte order.
The structure in_addr as used in inet_ntoa(),
inet_makeaddr(), inet_lnoaf() and inet_netof() is defined
in netinet/in.h as:
struct in_addr {
unsigned long int s_addr;
}
Note that on the i80x86 the host byte order is Least Sig-
nificant Byte first, whereas the network byte order, as
used on the Internet, is Most Significant Byte first.
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), getnetent(3), hosts(5), networks(5)
INET(3) Linux Programmer's Manual INET(3)
NAME
inet_aton, inet_addr, inet_network, inet_ntoa,
inet_makeaddr, inet_lnaof, inet_netof - Internet address
manipulation routines
SYNOPSIS
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
int inet_aton(const char *cp, struct in_addr *inp);
unsigned long int inet_addr(const char *cp);
unsigned long int inet_network(const char *cp);
char *inet_ntoa(struct in_addr in);
struct in_addr inet_makeaddr(int net, int host);
unsigned long int inet_lnaof(struct in_addr in);
unsigned long int inet_netof(struct in_addr in);
DESCRIPTION
inet_aton() converts the Internet host address cp from the
standard numbers-and-dots notation into binary data and
stores it in the structure that inp points to. inet_aton
returns nonzero if the address is valid, zero if not.
The inet_addr() function converts the Internet host
address cp from numbers-and-dots notation into binary data
in network byte order. If the input is invalid, -1 is
returned. This is an obsolete interface to inet_aton,
described immediately above; it is obsolete because -1 is
a valid address (255.255.255.255), and inet_aton provides
a cleaner way to indicate error return.
The inet_network() function extracts the network number in
network byte order from the address cp in numbers-and-dots
notation. If the input is invalid, -1 is returned.
The inet_ntoa() function converts the Internet host
address in given in network byte order to a string in
standard numbers-and-dots notation. The string is
returned in a statically allocated buffer, which subse-
quent calls will overwrite.
The inet_makeaddr() function makes an Internet host
address in network byte order by combining the network
number net with the local address host in network net,
both in local host byte order.
The inet_lnaof() function returns the local host address
part of the Internet address in. The local host address
is returned in local host byte order.
The inet_netof() function returns the network number part
of the Internet Address in. The network number is
returned in local host byte order.
The structure in_addr as used in inet_ntoa(),
inet_makeaddr(), inet_lnoaf() and inet_netof() is defined
in netinet/in.h as:
struct in_addr {
unsigned long int s_addr;
}
Note that on the i80x86 the host byte order is Least Sig-
nificant Byte first, whereas the network byte order, as
used on the Internet, is Most Significant Byte first.
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), getnetent(3), hosts(5), networks(5)
INET(3) Linux Programmer's Manual INET(3)
NAME
inet_aton, inet_addr, inet_network, inet_ntoa,
inet_makeaddr, inet_lnaof, inet_netof - Internet address
manipulation routines
SYNOPSIS
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
int inet_aton(const char *cp, struct in_addr *inp);
unsigned long int inet_addr(const char *cp);
unsigned long int inet_network(const char *cp);
char *inet_ntoa(struct in_addr in);
struct in_addr inet_makeaddr(int net, int host);
unsigned long int inet_lnaof(struct in_addr in);
unsigned long int inet_netof(struct in_addr in);
DESCRIPTION
inet_aton() converts the Internet host address cp from the
standard numbers-and-dots notation into binary data and
stores it in the structure that inp points to. inet_aton
returns nonzero if the address is valid, zero if not.
The inet_addr() function converts the Internet host
address cp from numbers-and-dots notation into binary data
in network byte order. If the input is invalid, -1 is
returned. This is an obsolete interface to inet_aton,
described immediately above; it is obsolete because -1 is
a valid address (255.255.255.255), and inet_aton provides
a cleaner way to indicate error return.
The inet_network() function extracts the network number in
network byte order from the address cp in numbers-and-dots
notation. If the input is invalid, -1 is returned.
The inet_ntoa() function converts the Internet host
address in given in network byte order to a string in
standard numbers-and-dots notation. The string is
returned in a statically allocated buffer, which subse-
quent calls will overwrite.
The inet_makeaddr() function makes an Internet host
address in network byte order by combining the network
number net with the local address host in network net,
both in local host byte order.
The inet_lnaof() function returns the local host address
part of the Internet address in. The local host address
is returned in local host byte order.
The inet_netof() function returns the network number part
of the Internet Address in. The network number is
returned in local host byte order.
The structure in_addr as used in inet_ntoa(),
inet_makeaddr(), inet_lnoaf() and inet_netof() is defined
in netinet/in.h as:
struct in_addr {
unsigned long int s_addr;
}
Note that on the i80x86 the host byte order is Least Sig-
nificant Byte first, whereas the network byte order, as
used on the Internet, is Most Significant Byte first.
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), getnetent(3), hosts(5), networks(5)
INET(3) Linux Programmer's Manual INET(3)
NAME
inet_aton, inet_addr, inet_network, inet_ntoa,
inet_makeaddr, inet_lnaof, inet_netof - Internet address
manipulation routines
SYNOPSIS
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
int inet_aton(const char *cp, struct in_addr *inp);
unsigned long int inet_addr(const char *cp);
unsigned long int inet_network(const char *cp);
char *inet_ntoa(struct in_addr in);
struct in_addr inet_makeaddr(int net, int host);
unsigned long int inet_lnaof(struct in_addr in);
unsigned long int inet_netof(struct in_addr in);
DESCRIPTION
inet_aton() converts the Internet host address cp from the
standard numbers-and-dots notation into binary data and
stores it in the structure that inp points to. inet_aton
returns nonzero if the address is valid, zero if not.
The inet_addr() function converts the Internet host
address cp from numbers-and-dots notation into binary data
in network byte order. If the input is invalid, -1 is
returned. This is an obsolete interface to inet_aton,
described immediately above; it is obsolete because -1 is
a valid address (255.255.255.255), and inet_aton provides
a cleaner way to indicate error return.
The inet_network() function extracts the network number in
network byte order from the address cp in numbers-and-dots
notation. If the input is invalid, -1 is returned.
The inet_ntoa() function converts the Internet host
address in given in network byte order to a string in
standard numbers-and-dots notation. The string is
returned in a statically allocated buffer, which subse-
quent calls will overwrite.
The inet_makeaddr() function makes an Internet host
address in network byte order by combining the network
number net with the local address host in network net,
both in local host byte order.
The inet_lnaof() function returns the local host address
part of the Internet address in. The local host address
is returned in local host byte order.
The inet_netof() function returns the network number part
of the Internet Address in. The network number is
returned in local host byte order.
The structure in_addr as used in inet_ntoa(),
inet_makeaddr(), inet_lnoaf() and inet_netof() is defined
in netinet/in.h as:
struct in_addr {
unsigned long int s_addr;
}
Note that on the i80x86 the host byte order is Least Sig-
nificant Byte first, whereas the network byte order, as
used on the Internet, is Most Significant Byte first.
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), getnetent(3), hosts(5), networks(5)
INET(3) Linux Programmer's Manual INET(3)
NAME
inet_aton, inet_addr, inet_network, inet_ntoa,
inet_makeaddr, inet_lnaof, inet_netof - Internet address
manipulation routines
SYNOPSIS
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
int inet_aton(const char *cp, struct in_addr *inp);
unsigned long int inet_addr(const char *cp);
unsigned long int inet_network(const char *cp);
char *inet_ntoa(struct in_addr in);
struct in_addr inet_makeaddr(int net, int host);
unsigned long int inet_lnaof(struct in_addr in);
unsigned long int inet_netof(struct in_addr in);
DESCRIPTION
inet_aton() converts the Internet host address cp from the
standard numbers-and-dots notation into binary data and
stores it in the structure that inp points to. inet_aton
returns nonzero if the address is valid, zero if not.
The inet_addr() function converts the Internet host
address cp from numbers-and-dots notation into binary data
in network byte order. If the input is invalid, -1 is
returned. This is an obsolete interface to inet_aton,
described immediately above; it is obsolete because -1 is
a valid address (255.255.255.255), and inet_aton provides
a cleaner way to indicate error return.
The inet_network() function extracts the network number in
network byte order from the address cp in numbers-and-dots
notation. If the input is invalid, -1 is returned.
The inet_ntoa() function converts the Internet host
address in given in network byte order to a string in
standard numbers-and-dots notation. The string is
returned in a statically allocated buffer, which subse-
quent calls will overwrite.
The inet_makeaddr() function makes an Internet host
address in network byte order by combining the network
number net with the local address host in network net,
both in local host byte order.
The inet_lnaof() function returns the local host address
part of the Internet address in. The local host address
is returned in local host byte order.
The inet_netof() function returns the network number part
of the Internet Address in. The network number is
returned in local host byte order.
The structure in_addr as used in inet_ntoa(),
inet_makeaddr(), inet_lnoaf() and inet_netof() is defined
in netinet/in.h as:
struct in_addr {
unsigned long int s_addr;
}
Note that on the i80x86 the host byte order is Least Sig-
nificant Byte first, whereas the network byte order, as
used on the Internet, is Most Significant Byte first.
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), getnetent(3), hosts(5), networks(5)
INET(3) Linux Programmer's Manual INET(3)
NAME
inet_aton, inet_addr, inet_network, inet_ntoa,
inet_makeaddr, inet_lnaof, inet_netof - Internet address
manipulation routines
SYNOPSIS
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
int inet_aton(const char *cp, struct in_addr *inp);
unsigned long int inet_addr(const char *cp);
unsigned long int inet_network(const char *cp);
char *inet_ntoa(struct in_addr in);
struct in_addr inet_makeaddr(int net, int host);
unsigned long int inet_lnaof(struct in_addr in);
unsigned long int inet_netof(struct in_addr in);
DESCRIPTION
inet_aton() converts the Internet host address cp from the
standard numbers-and-dots notation into binary data and
stores it in the structure that inp points to. inet_aton
returns nonzero if the address is valid, zero if not.
The inet_addr() function converts the Internet host
address cp from numbers-and-dots notation into binary data
in network byte order. If the input is invalid, -1 is
returned. This is an obsolete interface to inet_aton,
described immediately above; it is obsolete because -1 is
a valid address (255.255.255.255), and inet_aton provides
a cleaner way to indicate error return.
The inet_network() function extracts the network number in
network byte order from the address cp in numbers-and-dots
notation. If the input is invalid, -1 is returned.
The inet_ntoa() function converts the Internet host
address in given in network byte order to a string in
standard numbers-and-dots notation. The string is
returned in a statically allocated buffer, which subse-
quent calls will overwrite.
The inet_makeaddr() function makes an Internet host
address in network byte order by combining the network
number net with the local address host in network net,
both in local host byte order.
The inet_lnaof() function returns the local host address
part of the Internet address in. The local host address
is returned in local host byte order.
The inet_netof() function returns the network number part
of the Internet Address in. The network number is
returned in local host byte order.
The structure in_addr as used in inet_ntoa(),
inet_makeaddr(), inet_lnoaf() and inet_netof() is defined
in netinet/in.h as:
struct in_addr {
unsigned long int s_addr;
}
Note that on the i80x86 the host byte order is Least Sig-
nificant Byte first, whereas the network byte order, as
used on the Internet, is Most Significant Byte first.
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), getnetent(3), hosts(5), networks(5)
IOCTL(2) Linux Programmer's Manual IOCTL(2)
NAME
ioctl - control device
SYNOPSIS
#include <sys/ioctl.h>
int ioctl(int d, int request, ...)
[The "third" argument is traditionally char *argp, and
will be so named for this discussion.]
DESCRIPTION
The ioctl function manipulates the underlying device
parameters of special files. In particular, many operat-
ing characteristics of character special files (e.g. ter-
minals) may be controlled with ioctl requests. The argu-
ment d must be an open file descriptor.
An ioctl request has encoded in it whether the argument is
an in parameter or out parameter, and the size of the
argument argp in bytes. Macros and defines used in speci-
fying an ioctl request are located in the file
<sys/ioctl.h>.
RETURN VALUE
On success, zero is returned. On error, -1 is returned,
and errno is set appropriately.
ERRORS
EBADF d is not a valid descriptor.
ENOTTY d is not associated with a character special
device.
ENOTTY The specified request does not apply to the kind of
object that the descriptor d references.
EINVAL Request or argp is not valid.
CONFORMING TO
No single standard. Arguments, returns, and semantics of
ioctl(2) vary according to the device driver in question
(the call is used as a catch-all for operations that don't
cleanly fit the Unix stream I/O model). See ioctl_list(2)
for a list of many of the known ioctl calls. The ioctl
function call appeared in Version 7 AT-T Unix.
SEE ALSO
execve(2), fcntl(2), mt(4), sd(4), tty(4)
LIBSOCKET(7) libsocket Reference LIBSOCKET(7)
NAME
libsocket - libsocket Library Overview
SYNOPSIS
#include <sys/socket.h>
DESCRIPTION
libsocket is a socket-based networking library for DJGPP.
libsocket uses Windows 3.x and '95's networking code to
provide TCP/IP services to DJGPP programs when they are
run in a DOS box under Windows. It does this by using Win-
dows' Winsock Virtual Device Drivers (VxDs) via a DOS
Interrupt service.
libsocket requires Windows TCP/IP drivers to be installed
to work - see the Windows' Networking Control Panel.
The library is based on Linux's socket networking code.
This means that any programs using standard socket calls
should work (changes to the programs will probably be nec-
essary due to DOS's limitations). It also allows program-
mers with familiarity of standard socket calls to quickly
write programs using DJGPP.
Since it is based on Linux's code, the library looks for
configuration files with the same name as on Linux. These
files are host.conf, resolv.conf, hosts, networks and ser-
vices - on Linux these are found in /etc, but libsocket
looks for them in the Windows directory or a directory
specified by the environment variable LIBSOCKET.
host.conf and resolv.conf need creating - see resolver(5).
This process can be automated with netsetup(8).
The files hosts, networks and services are usually present
in the Windows directory, although they usually need edit-
ing. See hosts(5), networks(5) and services(5). The file
protocols is usually also be present in the Windows direc-
tory, but libsocket does not use this - see protocols(5).
COMPONENTS
The library provides the include files and linkable
libraries. These have the same names as on Linux (and
other socket-compatible OS's): socket.h and libsocket.a.
BUGS
The library doesn't work under Windows NT as it doesn't
have a Winsock VxD.
The library doesn't work with Winsock 2, which means it
will not work with Windows '98.
SEE ALSO
resolver(5), hosts(5), networks(5), services(5) and proto-
cols(5)
AVAILABILITY
This library is free software; you can redistribute it
and/or modify it under the terms of the GNU Library Gen-
eral Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your
option) any later version.
This library is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU Library General Public License for
more details.
You should have received a copy of the GNU Library General
Public License along with this library; if not, write to
the Free Software Foundation, Inc., 675 Mass Ave, Cam-
bridge, MA 02139, USA.
Copyright 1997, 1998 by Indrek Mandre
Copyright 1997, 1998 by Richard Dawe
Portions copyright (C) 1997-1998 by The RegDos Group
The main distribution site for this library is http://lib-
socket.home.ml.org/. The old distribution site for this
library is http://www.pld.ttu.ee/~indrek, the old main-
tainer's home page, from which there is a link to the new
site.
The documentation on the home page is likely to be more
up-to-date than these man pages.
AUTHORS
Indrek Mandre
Indrek was the main author for libsocket, but no
longer maintains it (see below).
<indrek@warp.edu.ee>
http://www.pld.ttu.ee/~indrek
Richard Dawe
Rich now maintains libsocket for Indrek.
<rd5718@bristol.ac.uk>
http://irix.bris.ac.uk/~rd5718/
CREDITS
Dan M. Hedlund
<hedl0036@tc.umn.edu>
http://www.geocities.com/SiliconValley/Peaks/8523/
His Winsock library is the base of this library.
Alfons Hoogervorst
<alfons@hoogervorst.demon.nl>
http://www.hoogervorst.demon.nl/~proteus
His dsock library helped me to get select() and
blocking recv() calls work. He's also the main-
tainer of the RegDos registry access code. He also
contributed some information about obtaining IP
addresses under Windows.
The RegDos Group
The registry access code was contributed by this
group of people - see Alfons Hoogervorst's details
below as he is the maintainer of this project.
Linus Torvalds
Linux is the best OS. I did most of the coding
under it.
DISCREDITS
Bill
<billg@microsoft.com>
http://www.microsoft.com/
The worst OS I've ever seen. It's slow. It crashes
all the time and it looks ugly.
LISTEN(2) Linux Programmer's Manual LISTEN(2)
NAME
listen - listen for connections on a socket
SYNOPSIS
#include <sys/socket.h>
int listen(int s, int backlog);
DESCRIPTION
To accept connections, a socket is first created with
socket(2), a willingness to accept incoming connections
and a queue limit for incoming connections are specified
with listen, and then the connections are accepted with
accept(2). The listen call applies only to sockets of
type SOCK_STREAM or SOCK_SEQPACKET.
The backlog parameter defines the maximum length the queue
of pending connections may grow to. If a connection
request arrives with the queue full the client may receive
an error with an indication of ECONNREFUSED, or, if the
underlying protocol supports retransmission, the request
may be ignored so that retries may succeed.
RETURN VALUE
On success, zero is returned. On error, -1 is returned,
and errno is set appropriately.
ERRORS
EBADF The argument s is not a valid descriptor.
ENOTSOCK
The argument s is not a socket.
EOPNOTSUPP
The socket is not of a type that supports the
operation listen.
CONFORMING TO
SVr4, 4.4BSD (the listen function call first appeared in
4.2BSD).
BUGS
If the socket is of type af_inet, and the backlog argument
is greater than the constant SO_MAXCONN (128 in 2.0.23),
it is silently truncated to SO_MAXCONN. For portable
applications don't rely on this value since BSD (and at
least some BSD derived systems) limit the backlog to 5.
SEE ALSO
accept(2), connect(2), socket(2)
NETSETUP(8) libsocket Reference NETSETUP(8)
NAME
netsetup - libsocket Library Networking Set-Up
SYNOPSIS
netsetup
DESCRIPTION
netsetup sets up various configuration files for lib-
socket.
netsetup is an interactive program that creates versions
of host.conf, resolv.conf and hosts, because these are not
usually present on Windows '95 computers. These are
required for libsocket's networking to function correctly.
The files created need to moved and renamed to the Windows
directory, usually C:\WINDOWS.
In order to create the files, netsetup needs the following
information:
Your computer's name and IP address
Your domain name
Whether there is a DNS server and its IP address
(if applicable)
The first piece of information is used to create the hosts
file. The remainder is used to create the host.conf and
resolv.conf files.
The hosts file created contains entries for localhost and
whatever name you entered for your computer. This file is
used to resolve names when no DNS server is present - it
is used to translate names to IP addresses, e.g. myserver
-> 192.168.0.2.
If there is no DNS server present, then netsetup will tell
libsocket to use the hosts file for name resolution before
using a DNS server. If one is present, then the order will
be reversed.
SEE ALSO
libsocket(7), hosts(5) and resolver(5).
NETWORKS(5) libsocket Reference NETWORKS(5)
NAME
networks - the network name to network IP address mapping
file
DESCRIPTION
This file tells the host name resolver the network compo-
nent of an IP address corresponding to each network name.
This is useful if there is no DNS server on the network.
It can also be used if the DNS server does not have a
record for a particular network name, but its IP address
is known.
The file is a plain ASCII file. Comments are denoted by a
hash at the start of a line. Each line has the following
format:
<IP address> <network name> <alias>
e.g.
# networks - network name to IP address translation
file
127 loopback
192.168.0 mynet intranet
There should always be a line refering to loopback. This
is the loopback device, and is always accessible.
Note 1: Windows doesn't use the aliases, so you will need
multiple lines for the same network IP address to fake
aliasing.
Note 2: The network IP address can be constructed from an
IP address and network mask, e.g. if you have an IP
address of 1.2.3.4 and a netmask of 255.255.0.0, then
AND'ing them gives a network IP address of 1.2.
FILES
/etc/networks (Linux), C:\WINDOWS\NETWORKS (Windows)
SEE ALSO
hosts(5)
PROTOCOLS(5) Linux Programmer's Manual PROTOCOLS(5)
NAME
protocols - the protocols definition file
DESCRIPTION
This file is a plain ASCII file, describing the various
DARPA internet protocols that are available from the
TCP/IP subsystem. It should be consulted instead of using
the numbers in the ARPA include files, or, even worse,
just guessing them. These numbers will occur in the proto-
col field of any ip header.
Keep this file untouched since changes would result in
incorrect ip packages. Protocol numbers and names are
specified by the DDN Network Information Center.
Each line is of the following format:
protocol number aliases ...
where the fields are delimited by spaces or tabs. Empty
lines and lines starting with a hash mark (#) are ignored.
Remainder of lines are also ignored from the occurrence of
a hash mark.
The field descriptions are:
protocol
the native name for the protocol. For example ip,
tcp or udp.
number the official number for this protocol as it will
appear within the ip header.
aliases
optional aliases for the protocol.
This file might be distributed over a network using a net-
workwide naming service like Yellow Pages/NIS or BIND/Hes-
oid.
FILES
/etc/protocols
The protocols definition file.
SEE ALSO
getprotoent(3)
READ(2) System calls READ(2)
NAME
read - read from a file descriptor
SYNOPSIS
#include <unistd.h>
ssize_t read(int fd, void *buf, size_t count);
DESCRIPTION
read() attempts to read up to count bytes from file
descriptor fd into the buffer starting at buf.
If count is zero, read() returns zero and has no other
results. If count is greater than SSIZE_MAX, the result
is unspecified.
RETURN VALUE
On success, the number of bytes read is returned (zero
indicates end of file), and the file position is advanced
by this number. It is not an error if this number is
smaller than the number of bytes requested; this may hap-
pen for example because fewer bytes are actually available
right now (maybe because we were close to end-of-file, or
because we are reading from a pipe, or from a terminal),
or because read() was interrupted by a signal. On error,
-1 is returned, and errno is set appropriately. In this
case it is left unspecified whether the file position (if
any) changes.
ERRORS
EINTR The call was interrupted by a signal before any
data was read.
EAGAIN Non-blocking I/O has been selected using O_NON-
BLOCK and no data was immediately available for
reading.
EIO I/O error. This will happen for example when the
process is in a background process group, tries to
read from its controlling tty, and either it is
ignoring or blocking SIGTTIN or its process group
is orphaned. It may also occur when there is a
low-level I/O error while reading from a disk or
tape.
EISDIR fd refers to a directory.
EBADF fd is not a valid file descriptor or is not open
for reading.
EINVAL fd is attached to an object which is unsuitable
for reading.
EFAULT buf is outside your accessible address space.
Other errors may occur, depending on the object connected
to fd. POSIX allows a read that is interrupted after
reading some data to return -1 (with errno set to EINTR)
or to return the number of bytes already read.
CONFORMING TO
SVr4, SVID, AT-T, POSIX, X/OPEN, BSD 4.3
RESTRICTIONS
On NFS file systems, reading small amounts of data will
only update the time stamp the first time, subsequent
calls may not do so. This is caused by client side
attribute caching, because most if not all NFS clients
leave atime updates to the server and client side reads
satisfied from the client's cache will not cause atime
updates on the server as there are no server side reads.
UNIX semantics can be obtained by disabling client side
attribute caching, but in most situations this will sub-
stantially increase server load and decrease performance.
SEE ALSO
readdir(2), write(2), write(2), fcntl(2), close(2),
lseek(2), select(2), readlink(2), ioctl(2), fread(3).
RECV(2) Linux Programmer's Manual RECV(2)
NAME
recv, recvfrom, recvmsg - receive a message from a socket
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
int recv(int s, void *buf, int len, unsigned int flags);
int recvfrom(int s, void *buf, int len, unsigned int flags
struct sockaddr *from, int *fromlen);
int recvmsg(int s, struct msghdr *msg, unsigned int
flags);
DESCRIPTION
The recvfrom and recvmsg are used to receive messages from
a socket, and may be used to receive data on a socket
whether or not it is connection-oriented.
If from is non-nil, and the socket is not connection-ori-
ented, the source address of the message is filled in.
Fromlen is a value-result parameter, initialized to the
size of the buffer associated with from, and modified on
return to indicate the actual size of the address stored
there.
The recv call is normally used only on a connected socket
(see connect(2)) and is identical to recvfrom with a nil
from parameter. As it is redundant, it may not be sup-
ported in future releases.
All three routines return the length of the message on
successful completion. If a message is too long to fit in
the supplied buffer, excess bytes may be discarded depend-
ing on the type of socket the message is received from
(see socket(2)).
If no messages are available at the socket, the receive
call waits for a message to arrive, unless the socket is
nonblocking (see fcntl(2)) in which case the value -1 is
returned and the external variable errno set to EWOULD-
BLOCK. The receive calls normally return any data avail-
able, up to the requested amount, rather than waiting for
receipt of the full amount requested; this behavior is
affected by the socket-level options SO_RCVLOWAT and
SO_RCVTIMEO described in getsockopt(2).
The select(2) call may be used to determine when more data
arrive.
The flags argument to a recv call is formed by or'ing one
or more of the values:
MSG_OOB process out-of-band data
MSG_PEEK
peek at incoming message
MSG_WAITALL
wait for full request or error
The MSG_OOB flag requests receipt of out-of-band
data that would not be received in the normal data
stream. Some protocols place expedited data at
the head of the normal data queue, and thus this
flag cannot be used with such protocols. The
MSG_PEEK flag causes the receive operation to
return data from the beginning of the receive
queue without removing that data from the queue.
Thus, a subsequent receive call will return the
same data. The MSG_WAITALL flag requests that the
operation block until the full request is satis-
fied. However, the call may still return less
data than requested if a signal is caught, an
error or disconnect occurs, or the next data to be
received is of a different type than that
returned.
The recvmsg call uses a msghdr structure to mini-
mize the number of directly supplied parameters.
This structure has the following form, as defined
in sys/socket.h:
struct msghdr {
caddr_t msg_name; /* optional address */
u_int msg_namelen; /* size of address */
struct iovec *msg_iov; /* scatter/gather array */
u_int msg_iovlen; /* # elements in msg_iov */
caddr_t msg_control; /* ancillary data, see below */
u_int msg_controllen; /* ancillary data buffer len */
int msg_flags; /* flags on received message */
};
Here msg_name and msg_namelen specify the destination
address if the socket is unconnected; msg_name may be
given as a null pointer if no names are desired or
required. Msg_iov and msg_iovlen describe scatter gather
locations, as discussed in readv(2). Msg_control, which
has length msg_controllen, points to a buffer for other
protocol control related messages or other miscellaneous
ancillary data. The messages are of the form:
struct cmsghdr {
u_int cmsg_len; /* data byte count, including hdr */
int cmsg_level; /* originating protocol */
int cmsg_type; /* protocol-specific type */
/* followed by
u_char cmsg_data[]; */
};
As an example, one could use this to learn of changes in
the data-stream in XNS/SPP, or in ISO, to obtain user-con-
nection-request data by requesting a recvmsg with no data
buffer provided immediately after an accept call.
Open file descriptors are now passed as ancillary data for
AF_UNIX domain sockets, with cmsg_level set to SOL_SOCKET
and cmsg_type set to SCM_RIGHTS.
The msg_flags field is set on return according to the mes-
sage received. MSG_EOR indicates end-of-record; the data
returned completed a record (generally used with sockets
of type SOCK_SEQPACKET). MSG_TRUNC indicates that the
trailing portion of a datagram was discarded because the
datagram was larger than the buffer supplied. MSG_CTRUNC
indicates that some control data were discarded due to
lack of space in the buffer for ancillary data. MSG_OOB
is returned to indicate that expedited or out-of-band data
were received.
RETURN VALUES
These calls return the number of bytes received, or -1 if
an error occurred.
ERRORS
EBADF The argument s is an invalid descriptor.
ENOTCONN
The socket is associated with a connection-ori-
ented protocol and has not been connected (see
connect(2) and accept(2)).
ENOTSOCK
The argument s does not refer to a socket.
EWOULDBLOCK
The socket is marked non-blocking, and the receive
operation would block, or a receive timeout had
been set, and the timeout expired before data were
received.
EINTR The receive was interrupted by delivery of a sig-
nal before any data were available.
EFAULT The receive buffer pointer(s) point outside the
process's address space.
CONFORMING TO
4.4BSD (these function calls first appeared in 4.2BSD).
SEE ALSO
fcntl(2), read(2), select(2), getsockopt(2), socket(2)
RECV(2) Linux Programmer's Manual RECV(2)
NAME
recv, recvfrom, recvmsg - receive a message from a socket
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
int recv(int s, void *buf, int len, unsigned int flags);
int recvfrom(int s, void *buf, int len, unsigned int flags
struct sockaddr *from, int *fromlen);
int recvmsg(int s, struct msghdr *msg, unsigned int
flags);
DESCRIPTION
The recvfrom and recvmsg are used to receive messages from
a socket, and may be used to receive data on a socket
whether or not it is connection-oriented.
If from is non-nil, and the socket is not connection-ori-
ented, the source address of the message is filled in.
Fromlen is a value-result parameter, initialized to the
size of the buffer associated with from, and modified on
return to indicate the actual size of the address stored
there.
The recv call is normally used only on a connected socket
(see connect(2)) and is identical to recvfrom with a nil
from parameter. As it is redundant, it may not be sup-
ported in future releases.
All three routines return the length of the message on
successful completion. If a message is too long to fit in
the supplied buffer, excess bytes may be discarded depend-
ing on the type of socket the message is received from
(see socket(2)).
If no messages are available at the socket, the receive
call waits for a message to arrive, unless the socket is
nonblocking (see fcntl(2)) in which case the value -1 is
returned and the external variable errno set to EWOULD-
BLOCK. The receive calls normally return any data avail-
able, up to the requested amount, rather than waiting for
receipt of the full amount requested; this behavior is
affected by the socket-level options SO_RCVLOWAT and
SO_RCVTIMEO described in getsockopt(2).
The select(2) call may be used to determine when more data
arrive.
The flags argument to a recv call is formed by or'ing one
or more of the values:
MSG_OOB process out-of-band data
MSG_PEEK
peek at incoming message
MSG_WAITALL
wait for full request or error
The MSG_OOB flag requests receipt of out-of-band
data that would not be received in the normal data
stream. Some protocols place expedited data at
the head of the normal data queue, and thus this
flag cannot be used with such protocols. The
MSG_PEEK flag causes the receive operation to
return data from the beginning of the receive
queue without removing that data from the queue.
Thus, a subsequent receive call will return the
same data. The MSG_WAITALL flag requests that the
operation block until the full request is satis-
fied. However, the call may still return less
data than requested if a signal is caught, an
error or disconnect occurs, or the next data to be
received is of a different type than that
returned.
The recvmsg call uses a msghdr structure to mini-
mize the number of directly supplied parameters.
This structure has the following form, as defined
in sys/socket.h:
struct msghdr {
caddr_t msg_name; /* optional address */
u_int msg_namelen; /* size of address */
struct iovec *msg_iov; /* scatter/gather array */
u_int msg_iovlen; /* # elements in msg_iov */
caddr_t msg_control; /* ancillary data, see below */
u_int msg_controllen; /* ancillary data buffer len */
int msg_flags; /* flags on received message */
};
Here msg_name and msg_namelen specify the destination
address if the socket is unconnected; msg_name may be
given as a null pointer if no names are desired or
required. Msg_iov and msg_iovlen describe scatter gather
locations, as discussed in readv(2). Msg_control, which
has length msg_controllen, points to a buffer for other
protocol control related messages or other miscellaneous
ancillary data. The messages are of the form:
struct cmsghdr {
u_int cmsg_len; /* data byte count, including hdr */
int cmsg_level; /* originating protocol */
int cmsg_type; /* protocol-specific type */
/* followed by
u_char cmsg_data[]; */
};
As an example, one could use this to learn of changes in
the data-stream in XNS/SPP, or in ISO, to obtain user-con-
nection-request data by requesting a recvmsg with no data
buffer provided immediately after an accept call.
Open file descriptors are now passed as ancillary data for
AF_UNIX domain sockets, with cmsg_level set to SOL_SOCKET
and cmsg_type set to SCM_RIGHTS.
The msg_flags field is set on return according to the mes-
sage received. MSG_EOR indicates end-of-record; the data
returned completed a record (generally used with sockets
of type SOCK_SEQPACKET). MSG_TRUNC indicates that the
trailing portion of a datagram was discarded because the
datagram was larger than the buffer supplied. MSG_CTRUNC
indicates that some control data were discarded due to
lack of space in the buffer for ancillary data. MSG_OOB
is returned to indicate that expedited or out-of-band data
were received.
RETURN VALUES
These calls return the number of bytes received, or -1 if
an error occurred.
ERRORS
EBADF The argument s is an invalid descriptor.
ENOTCONN
The socket is associated with a connection-ori-
ented protocol and has not been connected (see
connect(2) and accept(2)).
ENOTSOCK
The argument s does not refer to a socket.
EWOULDBLOCK
The socket is marked non-blocking, and the receive
operation would block, or a receive timeout had
been set, and the timeout expired before data were
received.
EINTR The receive was interrupted by delivery of a sig-
nal before any data were available.
EFAULT The receive buffer pointer(s) point outside the
process's address space.
CONFORMING TO
4.4BSD (these function calls first appeared in 4.2BSD).
SEE ALSO
fcntl(2), read(2), select(2), getsockopt(2), socket(2)
RECV(2) Linux Programmer's Manual RECV(2)
NAME
recv, recvfrom, recvmsg - receive a message from a socket
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
int recv(int s, void *buf, int len, unsigned int flags);
int recvfrom(int s, void *buf, int len, unsigned int flags
struct sockaddr *from, int *fromlen);
int recvmsg(int s, struct msghdr *msg, unsigned int
flags);
DESCRIPTION
The recvfrom and recvmsg are used to receive messages from
a socket, and may be used to receive data on a socket
whether or not it is connection-oriented.
If from is non-nil, and the socket is not connection-ori-
ented, the source address of the message is filled in.
Fromlen is a value-result parameter, initialized to the
size of the buffer associated with from, and modified on
return to indicate the actual size of the address stored
there.
The recv call is normally used only on a connected socket
(see connect(2)) and is identical to recvfrom with a nil
from parameter. As it is redundant, it may not be sup-
ported in future releases.
All three routines return the length of the message on
successful completion. If a message is too long to fit in
the supplied buffer, excess bytes may be discarded depend-
ing on the type of socket the message is received from
(see socket(2)).
If no messages are available at the socket, the receive
call waits for a message to arrive, unless the socket is
nonblocking (see fcntl(2)) in which case the value -1 is
returned and the external variable errno set to EWOULD-
BLOCK. The receive calls normally return any data avail-
able, up to the requested amount, rather than waiting for
receipt of the full amount requested; this behavior is
affected by the socket-level options SO_RCVLOWAT and
SO_RCVTIMEO described in getsockopt(2).
The select(2) call may be used to determine when more data
arrive.
The flags argument to a recv call is formed by or'ing one
or more of the values:
MSG_OOB process out-of-band data
MSG_PEEK
peek at incoming message
MSG_WAITALL
wait for full request or error
The MSG_OOB flag requests receipt of out-of-band
data that would not be received in the normal data
stream. Some protocols place expedited data at
the head of the normal data queue, and thus this
flag cannot be used with such protocols. The
MSG_PEEK flag causes the receive operation to
return data from the beginning of the receive
queue without removing that data from the queue.
Thus, a subsequent receive call will return the
same data. The MSG_WAITALL flag requests that the
operation block until the full request is satis-
fied. However, the call may still return less
data than requested if a signal is caught, an
error or disconnect occurs, or the next data to be
received is of a different type than that
returned.
The recvmsg call uses a msghdr structure to mini-
mize the number of directly supplied parameters.
This structure has the following form, as defined
in sys/socket.h:
struct msghdr {
caddr_t msg_name; /* optional address */
u_int msg_namelen; /* size of address */
struct iovec *msg_iov; /* scatter/gather array */
u_int msg_iovlen; /* # elements in msg_iov */
caddr_t msg_control; /* ancillary data, see below */
u_int msg_controllen; /* ancillary data buffer len */
int msg_flags; /* flags on received message */
};
Here msg_name and msg_namelen specify the destination
address if the socket is unconnected; msg_name may be
given as a null pointer if no names are desired or
required. Msg_iov and msg_iovlen describe scatter gather
locations, as discussed in readv(2). Msg_control, which
has length msg_controllen, points to a buffer for other
protocol control related messages or other miscellaneous
ancillary data. The messages are of the form:
struct cmsghdr {
u_int cmsg_len; /* data byte count, including hdr */
int cmsg_level; /* originating protocol */
int cmsg_type; /* protocol-specific type */
/* followed by
u_char cmsg_data[]; */
};
As an example, one could use this to learn of changes in
the data-stream in XNS/SPP, or in ISO, to obtain user-con-
nection-request data by requesting a recvmsg with no data
buffer provided immediately after an accept call.
Open file descriptors are now passed as ancillary data for
AF_UNIX domain sockets, with cmsg_level set to SOL_SOCKET
and cmsg_type set to SCM_RIGHTS.
The msg_flags field is set on return according to the mes-
sage received. MSG_EOR indicates end-of-record; the data
returned completed a record (generally used with sockets
of type SOCK_SEQPACKET). MSG_TRUNC indicates that the
trailing portion of a datagram was discarded because the
datagram was larger than the buffer supplied. MSG_CTRUNC
indicates that some control data were discarded due to
lack of space in the buffer for ancillary data. MSG_OOB
is returned to indicate that expedited or out-of-band data
were received.
RETURN VALUES
These calls return the number of bytes received, or -1 if
an error occurred.
ERRORS
EBADF The argument s is an invalid descriptor.
ENOTCONN
The socket is associated with a connection-ori-
ented protocol and has not been connected (see
connect(2) and accept(2)).
ENOTSOCK
The argument s does not refer to a socket.
EWOULDBLOCK
The socket is marked non-blocking, and the receive
operation would block, or a receive timeout had
been set, and the timeout expired before data were
received.
EINTR The receive was interrupted by delivery of a sig-
nal before any data were available.
EFAULT The receive buffer pointer(s) point outside the
process's address space.
CONFORMING TO
4.4BSD (these function calls first appeared in 4.2BSD).
SEE ALSO
fcntl(2), read(2), select(2), getsockopt(2), socket(2)
RESOLVER(3) Linux Programmer's Manual RESOLVER(3)
NAME
res_init, res_query, res_search, res_querydomain,
res_mkquery, res_send, dn_comp, dn_expand - resolver rou-
tines
SYNOPSIS
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>
extern struct state _res;
int res_init(void);
int res_query(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_search(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_querydomain(const char *name, const char *domain,
int class, int type, unsigned char *answer, int anslen);
int res_mkquery(int op, const char *dname, int class, int type,
char *data, int datalen, struct rrec *newrr, char *buf,
int buflen);
int res_send(const char *msg, int msglen, char *answer,
int anslen);
int dn_comp(unsigned char *exp_dn, unsigned char *comp_dn,
int length, unsigned char **dnptrs, unsigned char *exp_dn,
unsigned char **lastdnptr);
int dn_expand(unsigned char *msg, unsigned char *eomorig,
unsigned char *comp_dn, unsigned char *exp_dn, int length);
DESCRIPTION
These functions make queries to and interpret the
responses from Internet domain name servers.
The res_init() function reads the configuration files (see
resolv+(8)) to get the default domain name, search order
and name server address(es). If no server is given, the
local host is tried. If no domain is given, that associ-
ated with the local host is used. It can be overridden
with the environment variable LOCALDOMAIN. res_init() is
normally executed by the first call to one of the other
functions.
The res_query() function queries the name server for the
fully-qualified domain name name of specified type and
class. The reply is left in the buffer answer of length
anslen supplied by the caller.
The res_search() function makes a query and waits for the
response like res_query(), but in addition implements the
default and search rules controlled by RES_DEFNAMES and
RES_DNSRCH (see description of _res options below).
The res_querydomain() function makes a query using
res_query() on the concatenation of name and domain.
The following functions are lower-level routines used by
res_query().
The res_mkquery() function constructs a query message in
buf of length buflen for the domain name dname. The query
type op is usually QUERY, but can be any of the types
defined in <arpa/nameser.h>. newrr is currently unused.
The res_send() function sends a pre-formatted query given
in msg of length msglen and returns the answer in answer
which is of length anslen. It will call res_init(), if it
has not already been called.
The dn_comp() function compresses the domain name exp_dn
and stores it in the buffer comp_dn of length length. The
compression uses an array of pointers dnptrs to previously
compressed names in the current message. The first
pointer points to the beginning of the message and the
list ends with NULL. The limit of the array is specified
by lastdnptr. if dnptr is NULL, domain names are not com-
pressed. If lastdnptr is NULL, the list of labels is not
updated.
The dn_expand() function expands the compressed domain
name comp_dn to a full domain name, which is placed in the
buffer exp_dn of size length. The compressed name is con-
tained in a query or reply message, and msg points to the
beginning of the message.
The resolver routines use global configuration and state
information contained in the structure _res, which is
defined in <resolv.h>. The only field that is normally
manipulated by the user is _res.options. This field can
contain the bitwise ``or'' of the following options:
RES_INIT
True if res_init() has been called.
RES_DEBUG
Print debugging messages.
RES_AAONLY
Accept authoritative answers only. res_send() con-
tinues until it fins an authoritative answer or
returns an error. [Not currently implemented].
RES_USEVC
Use TCP connections for queries rather than UDP
datagrams.
RES_PRIMARY
Query primary domain name server only.
RES_IGNTC
Ignore truncation errors. Don't retry with TCP.
[Not currently implemented].
RES_RECURSE
Set the recursion desired bit in queries. Recur-
sion is carried out by the domain name server, not
by res_send(). [Enabled by default].
RES_DEFNAMES
If set, res_search() will append the default domain
name to single component names, ie. those that do
not contain a dot. [Enabled by default].
RES_STAYOPEN
Used with RES_USEVC to keep the TCP connection open
between queries.
RES_DNSRCH
If set, res_search() will search for host names in
the current domain and in parent domains. This
option is used by gethostbyname(3). [Enabled by
default].
RETURN VALUE
The res_init() function returns 0 on success, or -1 if an
error occurs.
The res_query(), res_search(), res_querydomain(),
res_mkquery() and res_send() functions return the length
of the response, or -1 if an error occurs.
The dn_comp() and dn_expand() functions return the length
of the compressed name, or -1 if an error occurs.
FILES
/etc/resolv.conf resolver configuration file
/etc/host.conf resolver configuration file
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), hostname(7), named(8), resolv+(8)
RESOLVER(3) Linux Programmer's Manual RESOLVER(3)
NAME
res_init, res_query, res_search, res_querydomain,
res_mkquery, res_send, dn_comp, dn_expand - resolver rou-
tines
SYNOPSIS
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>
extern struct state _res;
int res_init(void);
int res_query(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_search(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_querydomain(const char *name, const char *domain,
int class, int type, unsigned char *answer, int anslen);
int res_mkquery(int op, const char *dname, int class, int type,
char *data, int datalen, struct rrec *newrr, char *buf,
int buflen);
int res_send(const char *msg, int msglen, char *answer,
int anslen);
int dn_comp(unsigned char *exp_dn, unsigned char *comp_dn,
int length, unsigned char **dnptrs, unsigned char *exp_dn,
unsigned char **lastdnptr);
int dn_expand(unsigned char *msg, unsigned char *eomorig,
unsigned char *comp_dn, unsigned char *exp_dn, int length);
DESCRIPTION
These functions make queries to and interpret the
responses from Internet domain name servers.
The res_init() function reads the configuration files (see
resolv+(8)) to get the default domain name, search order
and name server address(es). If no server is given, the
local host is tried. If no domain is given, that associ-
ated with the local host is used. It can be overridden
with the environment variable LOCALDOMAIN. res_init() is
normally executed by the first call to one of the other
functions.
The res_query() function queries the name server for the
fully-qualified domain name name of specified type and
class. The reply is left in the buffer answer of length
anslen supplied by the caller.
The res_search() function makes a query and waits for the
response like res_query(), but in addition implements the
default and search rules controlled by RES_DEFNAMES and
RES_DNSRCH (see description of _res options below).
The res_querydomain() function makes a query using
res_query() on the concatenation of name and domain.
The following functions are lower-level routines used by
res_query().
The res_mkquery() function constructs a query message in
buf of length buflen for the domain name dname. The query
type op is usually QUERY, but can be any of the types
defined in <arpa/nameser.h>. newrr is currently unused.
The res_send() function sends a pre-formatted query given
in msg of length msglen and returns the answer in answer
which is of length anslen. It will call res_init(), if it
has not already been called.
The dn_comp() function compresses the domain name exp_dn
and stores it in the buffer comp_dn of length length. The
compression uses an array of pointers dnptrs to previously
compressed names in the current message. The first
pointer points to the beginning of the message and the
list ends with NULL. The limit of the array is specified
by lastdnptr. if dnptr is NULL, domain names are not com-
pressed. If lastdnptr is NULL, the list of labels is not
updated.
The dn_expand() function expands the compressed domain
name comp_dn to a full domain name, which is placed in the
buffer exp_dn of size length. The compressed name is con-
tained in a query or reply message, and msg points to the
beginning of the message.
The resolver routines use global configuration and state
information contained in the structure _res, which is
defined in <resolv.h>. The only field that is normally
manipulated by the user is _res.options. This field can
contain the bitwise ``or'' of the following options:
RES_INIT
True if res_init() has been called.
RES_DEBUG
Print debugging messages.
RES_AAONLY
Accept authoritative answers only. res_send() con-
tinues until it fins an authoritative answer or
returns an error. [Not currently implemented].
RES_USEVC
Use TCP connections for queries rather than UDP
datagrams.
RES_PRIMARY
Query primary domain name server only.
RES_IGNTC
Ignore truncation errors. Don't retry with TCP.
[Not currently implemented].
RES_RECURSE
Set the recursion desired bit in queries. Recur-
sion is carried out by the domain name server, not
by res_send(). [Enabled by default].
RES_DEFNAMES
If set, res_search() will append the default domain
name to single component names, ie. those that do
not contain a dot. [Enabled by default].
RES_STAYOPEN
Used with RES_USEVC to keep the TCP connection open
between queries.
RES_DNSRCH
If set, res_search() will search for host names in
the current domain and in parent domains. This
option is used by gethostbyname(3). [Enabled by
default].
RETURN VALUE
The res_init() function returns 0 on success, or -1 if an
error occurs.
The res_query(), res_search(), res_querydomain(),
res_mkquery() and res_send() functions return the length
of the response, or -1 if an error occurs.
The dn_comp() and dn_expand() functions return the length
of the compressed name, or -1 if an error occurs.
FILES
/etc/resolv.conf resolver configuration file
/etc/host.conf resolver configuration file
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), hostname(7), named(8), resolv+(8)
RESOLVER(3) Linux Programmer's Manual RESOLVER(3)
NAME
res_init, res_query, res_search, res_querydomain,
res_mkquery, res_send, dn_comp, dn_expand - resolver rou-
tines
SYNOPSIS
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>
extern struct state _res;
int res_init(void);
int res_query(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_search(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_querydomain(const char *name, const char *domain,
int class, int type, unsigned char *answer, int anslen);
int res_mkquery(int op, const char *dname, int class, int type,
char *data, int datalen, struct rrec *newrr, char *buf,
int buflen);
int res_send(const char *msg, int msglen, char *answer,
int anslen);
int dn_comp(unsigned char *exp_dn, unsigned char *comp_dn,
int length, unsigned char **dnptrs, unsigned char *exp_dn,
unsigned char **lastdnptr);
int dn_expand(unsigned char *msg, unsigned char *eomorig,
unsigned char *comp_dn, unsigned char *exp_dn, int length);
DESCRIPTION
These functions make queries to and interpret the
responses from Internet domain name servers.
The res_init() function reads the configuration files (see
resolv+(8)) to get the default domain name, search order
and name server address(es). If no server is given, the
local host is tried. If no domain is given, that associ-
ated with the local host is used. It can be overridden
with the environment variable LOCALDOMAIN. res_init() is
normally executed by the first call to one of the other
functions.
The res_query() function queries the name server for the
fully-qualified domain name name of specified type and
class. The reply is left in the buffer answer of length
anslen supplied by the caller.
The res_search() function makes a query and waits for the
response like res_query(), but in addition implements the
default and search rules controlled by RES_DEFNAMES and
RES_DNSRCH (see description of _res options below).
The res_querydomain() function makes a query using
res_query() on the concatenation of name and domain.
The following functions are lower-level routines used by
res_query().
The res_mkquery() function constructs a query message in
buf of length buflen for the domain name dname. The query
type op is usually QUERY, but can be any of the types
defined in <arpa/nameser.h>. newrr is currently unused.
The res_send() function sends a pre-formatted query given
in msg of length msglen and returns the answer in answer
which is of length anslen. It will call res_init(), if it
has not already been called.
The dn_comp() function compresses the domain name exp_dn
and stores it in the buffer comp_dn of length length. The
compression uses an array of pointers dnptrs to previously
compressed names in the current message. The first
pointer points to the beginning of the message and the
list ends with NULL. The limit of the array is specified
by lastdnptr. if dnptr is NULL, domain names are not com-
pressed. If lastdnptr is NULL, the list of labels is not
updated.
The dn_expand() function expands the compressed domain
name comp_dn to a full domain name, which is placed in the
buffer exp_dn of size length. The compressed name is con-
tained in a query or reply message, and msg points to the
beginning of the message.
The resolver routines use global configuration and state
information contained in the structure _res, which is
defined in <resolv.h>. The only field that is normally
manipulated by the user is _res.options. This field can
contain the bitwise ``or'' of the following options:
RES_INIT
True if res_init() has been called.
RES_DEBUG
Print debugging messages.
RES_AAONLY
Accept authoritative answers only. res_send() con-
tinues until it fins an authoritative answer or
returns an error. [Not currently implemented].
RES_USEVC
Use TCP connections for queries rather than UDP
datagrams.
RES_PRIMARY
Query primary domain name server only.
RES_IGNTC
Ignore truncation errors. Don't retry with TCP.
[Not currently implemented].
RES_RECURSE
Set the recursion desired bit in queries. Recur-
sion is carried out by the domain name server, not
by res_send(). [Enabled by default].
RES_DEFNAMES
If set, res_search() will append the default domain
name to single component names, ie. those that do
not contain a dot. [Enabled by default].
RES_STAYOPEN
Used with RES_USEVC to keep the TCP connection open
between queries.
RES_DNSRCH
If set, res_search() will search for host names in
the current domain and in parent domains. This
option is used by gethostbyname(3). [Enabled by
default].
RETURN VALUE
The res_init() function returns 0 on success, or -1 if an
error occurs.
The res_query(), res_search(), res_querydomain(),
res_mkquery() and res_send() functions return the length
of the response, or -1 if an error occurs.
The dn_comp() and dn_expand() functions return the length
of the compressed name, or -1 if an error occurs.
FILES
/etc/resolv.conf resolver configuration file
/etc/host.conf resolver configuration file
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), hostname(7), named(8), resolv+(8)
RESOLVER(3) Linux Programmer's Manual RESOLVER(3)
NAME
res_init, res_query, res_search, res_querydomain,
res_mkquery, res_send, dn_comp, dn_expand - resolver rou-
tines
SYNOPSIS
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>
extern struct state _res;
int res_init(void);
int res_query(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_search(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_querydomain(const char *name, const char *domain,
int class, int type, unsigned char *answer, int anslen);
int res_mkquery(int op, const char *dname, int class, int type,
char *data, int datalen, struct rrec *newrr, char *buf,
int buflen);
int res_send(const char *msg, int msglen, char *answer,
int anslen);
int dn_comp(unsigned char *exp_dn, unsigned char *comp_dn,
int length, unsigned char **dnptrs, unsigned char *exp_dn,
unsigned char **lastdnptr);
int dn_expand(unsigned char *msg, unsigned char *eomorig,
unsigned char *comp_dn, unsigned char *exp_dn, int length);
DESCRIPTION
These functions make queries to and interpret the
responses from Internet domain name servers.
The res_init() function reads the configuration files (see
resolv+(8)) to get the default domain name, search order
and name server address(es). If no server is given, the
local host is tried. If no domain is given, that associ-
ated with the local host is used. It can be overridden
with the environment variable LOCALDOMAIN. res_init() is
normally executed by the first call to one of the other
functions.
The res_query() function queries the name server for the
fully-qualified domain name name of specified type and
class. The reply is left in the buffer answer of length
anslen supplied by the caller.
The res_search() function makes a query and waits for the
response like res_query(), but in addition implements the
default and search rules controlled by RES_DEFNAMES and
RES_DNSRCH (see description of _res options below).
The res_querydomain() function makes a query using
res_query() on the concatenation of name and domain.
The following functions are lower-level routines used by
res_query().
The res_mkquery() function constructs a query message in
buf of length buflen for the domain name dname. The query
type op is usually QUERY, but can be any of the types
defined in <arpa/nameser.h>. newrr is currently unused.
The res_send() function sends a pre-formatted query given
in msg of length msglen and returns the answer in answer
which is of length anslen. It will call res_init(), if it
has not already been called.
The dn_comp() function compresses the domain name exp_dn
and stores it in the buffer comp_dn of length length. The
compression uses an array of pointers dnptrs to previously
compressed names in the current message. The first
pointer points to the beginning of the message and the
list ends with NULL. The limit of the array is specified
by lastdnptr. if dnptr is NULL, domain names are not com-
pressed. If lastdnptr is NULL, the list of labels is not
updated.
The dn_expand() function expands the compressed domain
name comp_dn to a full domain name, which is placed in the
buffer exp_dn of size length. The compressed name is con-
tained in a query or reply message, and msg points to the
beginning of the message.
The resolver routines use global configuration and state
information contained in the structure _res, which is
defined in <resolv.h>. The only field that is normally
manipulated by the user is _res.options. This field can
contain the bitwise ``or'' of the following options:
RES_INIT
True if res_init() has been called.
RES_DEBUG
Print debugging messages.
RES_AAONLY
Accept authoritative answers only. res_send() con-
tinues until it fins an authoritative answer or
returns an error. [Not currently implemented].
RES_USEVC
Use TCP connections for queries rather than UDP
datagrams.
RES_PRIMARY
Query primary domain name server only.
RES_IGNTC
Ignore truncation errors. Don't retry with TCP.
[Not currently implemented].
RES_RECURSE
Set the recursion desired bit in queries. Recur-
sion is carried out by the domain name server, not
by res_send(). [Enabled by default].
RES_DEFNAMES
If set, res_search() will append the default domain
name to single component names, ie. those that do
not contain a dot. [Enabled by default].
RES_STAYOPEN
Used with RES_USEVC to keep the TCP connection open
between queries.
RES_DNSRCH
If set, res_search() will search for host names in
the current domain and in parent domains. This
option is used by gethostbyname(3). [Enabled by
default].
RETURN VALUE
The res_init() function returns 0 on success, or -1 if an
error occurs.
The res_query(), res_search(), res_querydomain(),
res_mkquery() and res_send() functions return the length
of the response, or -1 if an error occurs.
The dn_comp() and dn_expand() functions return the length
of the compressed name, or -1 if an error occurs.
FILES
/etc/resolv.conf resolver configuration file
/etc/host.conf resolver configuration file
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), hostname(7), named(8), resolv+(8)
RESOLVER(3) Linux Programmer's Manual RESOLVER(3)
NAME
res_init, res_query, res_search, res_querydomain,
res_mkquery, res_send, dn_comp, dn_expand - resolver rou-
tines
SYNOPSIS
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>
extern struct state _res;
int res_init(void);
int res_query(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_search(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_querydomain(const char *name, const char *domain,
int class, int type, unsigned char *answer, int anslen);
int res_mkquery(int op, const char *dname, int class, int type,
char *data, int datalen, struct rrec *newrr, char *buf,
int buflen);
int res_send(const char *msg, int msglen, char *answer,
int anslen);
int dn_comp(unsigned char *exp_dn, unsigned char *comp_dn,
int length, unsigned char **dnptrs, unsigned char *exp_dn,
unsigned char **lastdnptr);
int dn_expand(unsigned char *msg, unsigned char *eomorig,
unsigned char *comp_dn, unsigned char *exp_dn, int length);
DESCRIPTION
These functions make queries to and interpret the
responses from Internet domain name servers.
The res_init() function reads the configuration files (see
resolv+(8)) to get the default domain name, search order
and name server address(es). If no server is given, the
local host is tried. If no domain is given, that associ-
ated with the local host is used. It can be overridden
with the environment variable LOCALDOMAIN. res_init() is
normally executed by the first call to one of the other
functions.
The res_query() function queries the name server for the
fully-qualified domain name name of specified type and
class. The reply is left in the buffer answer of length
anslen supplied by the caller.
The res_search() function makes a query and waits for the
response like res_query(), but in addition implements the
default and search rules controlled by RES_DEFNAMES and
RES_DNSRCH (see description of _res options below).
The res_querydomain() function makes a query using
res_query() on the concatenation of name and domain.
The following functions are lower-level routines used by
res_query().
The res_mkquery() function constructs a query message in
buf of length buflen for the domain name dname. The query
type op is usually QUERY, but can be any of the types
defined in <arpa/nameser.h>. newrr is currently unused.
The res_send() function sends a pre-formatted query given
in msg of length msglen and returns the answer in answer
which is of length anslen. It will call res_init(), if it
has not already been called.
The dn_comp() function compresses the domain name exp_dn
and stores it in the buffer comp_dn of length length. The
compression uses an array of pointers dnptrs to previously
compressed names in the current message. The first
pointer points to the beginning of the message and the
list ends with NULL. The limit of the array is specified
by lastdnptr. if dnptr is NULL, domain names are not com-
pressed. If lastdnptr is NULL, the list of labels is not
updated.
The dn_expand() function expands the compressed domain
name comp_dn to a full domain name, which is placed in the
buffer exp_dn of size length. The compressed name is con-
tained in a query or reply message, and msg points to the
beginning of the message.
The resolver routines use global configuration and state
information contained in the structure _res, which is
defined in <resolv.h>. The only field that is normally
manipulated by the user is _res.options. This field can
contain the bitwise ``or'' of the following options:
RES_INIT
True if res_init() has been called.
RES_DEBUG
Print debugging messages.
RES_AAONLY
Accept authoritative answers only. res_send() con-
tinues until it fins an authoritative answer or
returns an error. [Not currently implemented].
RES_USEVC
Use TCP connections for queries rather than UDP
datagrams.
RES_PRIMARY
Query primary domain name server only.
RES_IGNTC
Ignore truncation errors. Don't retry with TCP.
[Not currently implemented].
RES_RECURSE
Set the recursion desired bit in queries. Recur-
sion is carried out by the domain name server, not
by res_send(). [Enabled by default].
RES_DEFNAMES
If set, res_search() will append the default domain
name to single component names, ie. those that do
not contain a dot. [Enabled by default].
RES_STAYOPEN
Used with RES_USEVC to keep the TCP connection open
between queries.
RES_DNSRCH
If set, res_search() will search for host names in
the current domain and in parent domains. This
option is used by gethostbyname(3). [Enabled by
default].
RETURN VALUE
The res_init() function returns 0 on success, or -1 if an
error occurs.
The res_query(), res_search(), res_querydomain(),
res_mkquery() and res_send() functions return the length
of the response, or -1 if an error occurs.
The dn_comp() and dn_expand() functions return the length
of the compressed name, or -1 if an error occurs.
FILES
/etc/resolv.conf resolver configuration file
/etc/host.conf resolver configuration file
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), hostname(7), named(8), resolv+(8)
RESOLVER(3) Linux Programmer's Manual RESOLVER(3)
NAME
res_init, res_query, res_search, res_querydomain,
res_mkquery, res_send, dn_comp, dn_expand - resolver rou-
tines
SYNOPSIS
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>
extern struct state _res;
int res_init(void);
int res_query(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_search(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_querydomain(const char *name, const char *domain,
int class, int type, unsigned char *answer, int anslen);
int res_mkquery(int op, const char *dname, int class, int type,
char *data, int datalen, struct rrec *newrr, char *buf,
int buflen);
int res_send(const char *msg, int msglen, char *answer,
int anslen);
int dn_comp(unsigned char *exp_dn, unsigned char *comp_dn,
int length, unsigned char **dnptrs, unsigned char *exp_dn,
unsigned char **lastdnptr);
int dn_expand(unsigned char *msg, unsigned char *eomorig,
unsigned char *comp_dn, unsigned char *exp_dn, int length);
DESCRIPTION
These functions make queries to and interpret the
responses from Internet domain name servers.
The res_init() function reads the configuration files (see
resolv+(8)) to get the default domain name, search order
and name server address(es). If no server is given, the
local host is tried. If no domain is given, that associ-
ated with the local host is used. It can be overridden
with the environment variable LOCALDOMAIN. res_init() is
normally executed by the first call to one of the other
functions.
The res_query() function queries the name server for the
fully-qualified domain name name of specified type and
class. The reply is left in the buffer answer of length
anslen supplied by the caller.
The res_search() function makes a query and waits for the
response like res_query(), but in addition implements the
default and search rules controlled by RES_DEFNAMES and
RES_DNSRCH (see description of _res options below).
The res_querydomain() function makes a query using
res_query() on the concatenation of name and domain.
The following functions are lower-level routines used by
res_query().
The res_mkquery() function constructs a query message in
buf of length buflen for the domain name dname. The query
type op is usually QUERY, but can be any of the types
defined in <arpa/nameser.h>. newrr is currently unused.
The res_send() function sends a pre-formatted query given
in msg of length msglen and returns the answer in answer
which is of length anslen. It will call res_init(), if it
has not already been called.
The dn_comp() function compresses the domain name exp_dn
and stores it in the buffer comp_dn of length length. The
compression uses an array of pointers dnptrs to previously
compressed names in the current message. The first
pointer points to the beginning of the message and the
list ends with NULL. The limit of the array is specified
by lastdnptr. if dnptr is NULL, domain names are not com-
pressed. If lastdnptr is NULL, the list of labels is not
updated.
The dn_expand() function expands the compressed domain
name comp_dn to a full domain name, which is placed in the
buffer exp_dn of size length. The compressed name is con-
tained in a query or reply message, and msg points to the
beginning of the message.
The resolver routines use global configuration and state
information contained in the structure _res, which is
defined in <resolv.h>. The only field that is normally
manipulated by the user is _res.options. This field can
contain the bitwise ``or'' of the following options:
RES_INIT
True if res_init() has been called.
RES_DEBUG
Print debugging messages.
RES_AAONLY
Accept authoritative answers only. res_send() con-
tinues until it fins an authoritative answer or
returns an error. [Not currently implemented].
RES_USEVC
Use TCP connections for queries rather than UDP
datagrams.
RES_PRIMARY
Query primary domain name server only.
RES_IGNTC
Ignore truncation errors. Don't retry with TCP.
[Not currently implemented].
RES_RECURSE
Set the recursion desired bit in queries. Recur-
sion is carried out by the domain name server, not
by res_send(). [Enabled by default].
RES_DEFNAMES
If set, res_search() will append the default domain
name to single component names, ie. those that do
not contain a dot. [Enabled by default].
RES_STAYOPEN
Used with RES_USEVC to keep the TCP connection open
between queries.
RES_DNSRCH
If set, res_search() will search for host names in
the current domain and in parent domains. This
option is used by gethostbyname(3). [Enabled by
default].
RETURN VALUE
The res_init() function returns 0 on success, or -1 if an
error occurs.
The res_query(), res_search(), res_querydomain(),
res_mkquery() and res_send() functions return the length
of the response, or -1 if an error occurs.
The dn_comp() and dn_expand() functions return the length
of the compressed name, or -1 if an error occurs.
FILES
/etc/resolv.conf resolver configuration file
/etc/host.conf resolver configuration file
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), hostname(7), named(8), resolv+(8)
RESOLVER(3) Linux Programmer's Manual RESOLVER(3)
NAME
res_init, res_query, res_search, res_querydomain,
res_mkquery, res_send, dn_comp, dn_expand - resolver rou-
tines
SYNOPSIS
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>
extern struct state _res;
int res_init(void);
int res_query(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_search(const char *dname, int class, int type,
unsigned char *answer, int anslen);
int res_querydomain(const char *name, const char *domain,
int class, int type, unsigned char *answer, int anslen);
int res_mkquery(int op, const char *dname, int class, int type,
char *data, int datalen, struct rrec *newrr, char *buf,
int buflen);
int res_send(const char *msg, int msglen, char *answer,
int anslen);
int dn_comp(unsigned char *exp_dn, unsigned char *comp_dn,
int length, unsigned char **dnptrs, unsigned char *exp_dn,
unsigned char **lastdnptr);
int dn_expand(unsigned char *msg, unsigned char *eomorig,
unsigned char *comp_dn, unsigned char *exp_dn, int length);
DESCRIPTION
These functions make queries to and interpret the
responses from Internet domain name servers.
The res_init() function reads the configuration files (see
resolv+(8)) to get the default domain name, search order
and name server address(es). If no server is given, the
local host is tried. If no domain is given, that associ-
ated with the local host is used. It can be overridden
with the environment variable LOCALDOMAIN. res_init() is
normally executed by the first call to one of the other
functions.
The res_query() function queries the name server for the
fully-qualified domain name name of specified type and
class. The reply is left in the buffer answer of length
anslen supplied by the caller.
The res_search() function makes a query and waits for the
response like res_query(), but in addition implements the
default and search rules controlled by RES_DEFNAMES and
RES_DNSRCH (see description of _res options below).
The res_querydomain() function makes a query using
res_query() on the concatenation of name and domain.
The following functions are lower-level routines used by
res_query().
The res_mkquery() function constructs a query message in
buf of length buflen for the domain name dname. The query
type op is usually QUERY, but can be any of the types
defined in <arpa/nameser.h>. newrr is currently unused.
The res_send() function sends a pre-formatted query given
in msg of length msglen and returns the answer in answer
which is of length anslen. It will call res_init(), if it
has not already been called.
The dn_comp() function compresses the domain name exp_dn
and stores it in the buffer comp_dn of length length. The
compression uses an array of pointers dnptrs to previously
compressed names in the current message. The first
pointer points to the beginning of the message and the
list ends with NULL. The limit of the array is specified
by lastdnptr. if dnptr is NULL, domain names are not com-
pressed. If lastdnptr is NULL, the list of labels is not
updated.
The dn_expand() function expands the compressed domain
name comp_dn to a full domain name, which is placed in the
buffer exp_dn of size length. The compressed name is con-
tained in a query or reply message, and msg points to the
beginning of the message.
The resolver routines use global configuration and state
information contained in the structure _res, which is
defined in <resolv.h>. The only field that is normally
manipulated by the user is _res.options. This field can
contain the bitwise ``or'' of the following options:
RES_INIT
True if res_init() has been called.
RES_DEBUG
Print debugging messages.
RES_AAONLY
Accept authoritative answers only. res_send() con-
tinues until it fins an authoritative answer or
returns an error. [Not currently implemented].
RES_USEVC
Use TCP connections for queries rather than UDP
datagrams.
RES_PRIMARY
Query primary domain name server only.
RES_IGNTC
Ignore truncation errors. Don't retry with TCP.
[Not currently implemented].
RES_RECURSE
Set the recursion desired bit in queries. Recur-
sion is carried out by the domain name server, not
by res_send(). [Enabled by default].
RES_DEFNAMES
If set, res_search() will append the default domain
name to single component names, ie. those that do
not contain a dot. [Enabled by default].
RES_STAYOPEN
Used with RES_USEVC to keep the TCP connection open
between queries.
RES_DNSRCH
If set, res_search() will search for host names in
the current domain and in parent domains. This
option is used by gethostbyname(3). [Enabled by
default].
RETURN VALUE
The res_init() function returns 0 on success, or -1 if an
error occurs.
The res_query(), res_search(), res_querydomain(),
res_mkquery() and res_send() functions return the length
of the response, or -1 if an error occurs.
The dn_comp() and dn_expand() functions return the length
of the compressed name, or -1 if an error occurs.
FILES
/etc/resolv.conf resolver configuration file
/etc/host.conf resolver configuration file
CONFORMING TO
BSD 4.3
SEE ALSO
gethostbyname(3), hostname(7), named(8), resolv+(8)
RESOLVER(5) 11, RESOLVER(5)
NAME
resolver - resolver configuration file
SYNOPSIS
/etc/resolv.conf
DESCRIPTION
The resolver is a set of routines in the C library
(resolv(3)) that provide access to the Internet Domain
Name System. The resolver configuration file contains
information that is read by the resolver routines the
first time they are invoked by a process. The file is
designed to be human readable and contains a list of key-
words with values that provide various types of resolver
information.
On a normally configured system this file should not be
necessary. The only name server to be queried will be on
the local machine, the domain name is determined from the
host name, and the domain search path is constructed from
the domain name.
The different configuration options are:
nameserver
Internet address (in dot notation) of a name server
that the resolver should query. Up to MAXNS (cur-
rently 3) name servers may be listed, one per key-
word. If there are multiple servers, the resolver
library queries them in the order listed. If no
nameserver entries are present, the default is to
use the name server on the local machine. (The
algorithm used is to try a name server, and if the
query times out, try the next, until out of name
servers, then repeat trying all the name servers
until a maximum number of retries are made).
domain Local domain name. Most queries for names within
this domain can use short names relative to the
local domain. If no domain entry is present, the
domain is determined from the local host name
returned by gethostname(2); the domain part is
taken to be everything after the first `.'.
Finally, if the host name does not contain a domain
part, the root domain is assumed.
search Search list for host-name lookup. The search list
is normally determined from the local domain name;
by default, it contains only the local domain name.
This may be changed by listing the desired domain
search path following the search keyword with
spaces or tabs separating the names. Most resolver
queries will be attempted using each component of
the search path in turn until a match is found.
Note that this process may be slow and will gener-
ate a lot of network traffic if the servers for the
listed domains are not local, and that queries will
time out if no server is available for one of the
domains.
The search list is currently limited to six domains
with a total of 256 characters.
sortlist
Sortlist allows addresses returned by gethostbyname
to be sorted. A sortlist is specified by IP
address netmask pairs. The netmask is optional and
defaults to the natural netmask of the net. The IP
address and optional network pairs are separated by
slashes. Up to 10 pairs may be specified.
e.g. sortlist 130.155.160.0/255.255.240.0
130.155.0.0
options
Options allows certain internal resolver variables
to be modified. The syntax is
options option ...
where option is one of the following:
debug -- sets RES_DEBUG in _res.options.
ndots:n -- sets a threshold for the number of dots
which must appear in a name given to res_query (see
resolver(3)) before an initial absolute query will
be made. The default for n is ``1'', meaning that
if there are any dots in a name, the name will be
tried first as an absolute name before any search
list elements are appended to it.
The domain and search keywords are mutually exclusive. If
more than one instance of these keywords is present, the
last instance wins.
The search keyword of a system's resolv.conf file can be
overridden on a per-process basis by setting the environ-
ment variable ``LOCALDOMAIN'' to a space-separated list of
search domains.
The options keyword of a system's resolv.conf file can be
amended on a per-process basis by setting the environment
variable ``RES_OPTIONS'' to a space-separated list of
resolver options as explained above under options.
The keyword and value must appear on a single line, and
the keyword (e.g. nameserver) must start the line. The
November 2
RESOLVER(5) 11, RESOLVER(5)
value follows the keyword, separated by white space.
FILES
/etc/resolv.conf
SEE ALSO
gethostbyname(3), resolver(3), hostname(7), named(8)
Name Server Operations Guide for BIND
SELECT(2) Linux Programmer's Manual SELECT(2)
NAME
select, FD_CLR, FD_ISSET, FD_SET, FD_ZERO - synchronous
I/O multiplexing
SYNOPSIS
#include <sys/time.h>
#include <sys/types.h>
#include <unistd.h>
int select(int n, fd_set *readfds, fd_set *writefds,
fd_set *exceptfds, struct timeval *timeout);
FD_CLR(int fd, fd_set *set);
FD_ISSET(int fd, fd_set *set);
FD_SET(int fd, fd_set *set);
FD_ZERO(fd_set *set);
DESCRIPTION
select waits for a number of file descriptors to change
status.
Three independent sets of descriptors are watched. Those
listed in readfds will be watched to see if characters
become available for reading, those in writefds will be
watched to see if it is ok to immediately write on them,
and those in exceptfds will be watched for exceptions. On
exit, the sets are modified in place to indicate which
descriptors actually changed status.
Four macros are provided to manipulate the sets. FD_ZERO
will clear a set. FD_SET and FD_CLR add or remove a given
descriptor from a set. FD_ISSET tests to see if a
descriptor is part of the set; this is useful after select
returns.
n is the highest-numbered descriptor in any of the three
sets, plus 1.
timeout is an upper bound on the amount of time elapsed
before select returns. It may be zero, causing select to
return immediately. If timeout is NULL (no timeout),
select can block indefinitely.
RETURN VALUE
On success, select returns the number of descriptors con-
tained in the descriptor sets, which may be zero if the
timeout expires before anything interesting happens. On
error, -1 is returned, and errno is set appropriately; the
sets and timeout become undefined, so do not rely on their
contents after an error.
ERRORS
EBADF An invalid file descriptor was given in one of the
sets.
EINTR A non blocked signal was caught.
EINVAL n is negative.
ENOMEM select was unable to allocate memory for internal
tables.
NOTES
Some code calls select with all three sets empty, n zero,
and a non-null timeout as a fairly portable way to sleep
with subsecond precision.
On Linux, timeout is modified to reflect the amount of
time not slept; most other implementations do not do this.
This causes problems both when Linux code which reads
timeout is ported to other operating systems, and when
code is ported to Linux that reuses a struct timeval for
multiple selects in a loop without reinitializing it.
Consider timeout to be undefined after select returns.
EXAMPLE
#include <stdio.h>
#include <sys/time.h>
#include <sys/types.h>
#include <unistd.h>
int
main(void)
{
fd_set rfds;
struct timeval tv;
int retval;
/* Watch stdin (fd 0) to see when it has input. */
FD_ZERO(-rfds);
FD_SET(0, -rfds);
/* Wait up to five seconds. */
tv.tv_sec = 5;
tv.tv_usec = 0;
retval = select(1, -rfds, NULL, NULL, -tv);
/* Don't rely on the value of tv now! */
if (retval)
printf("Data is available now.\n");
/* FD_ISSET(0, -rfds) will be true. */
else
printf("No data within five seconds.\n");
exit(0);
}
CONFORMING TO
4.4BSD (the select function first appeared in 4.2BSD).
Generally portable to/from non-BSD systems supporting
clones of the BSD socket layer (including System V vari-
ants). However, note that the System V variant typically
sets the timeout variable before exit, but the BSD variant
does not.
SEE ALSO
accept(2), connect(2), read(2), recv(2), send(2),
write(2).
SEND(2) Linux Programmer's Manual SEND(2)
NAME
send, sendto, sendmsg - send a message from a socket
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
int send(int s, const void *msg, int len, unsigned int
flags);
int sendto(int s, const void *msg, int len, unsigned int
flags, const struct sockaddr *to, int tolen);
int sendmsg(int s, const struct msghdr *msg, unsigned int
flags);
DESCRIPTION
WARNING: This is a BSD man page. As of Linux 0.99.11,
sendmsg was not implemented.
Send, sendto, and sendmsg are used to transmit a message
to another socket. Send may be used only when the socket
is in a connected state, while sendto and sendmsg may be
used at any time.
The address of the target is given by to with tolen speci-
fying its size. The length of the message is given by
len. If the message is too long to pass atomically
through the underlying protocol, the error EMSGSIZE is
returned, and the message is not transmitted.
No indication of failure to deliver is implicit in a send.
Locally detected errors are indicated by a return value of
-1.
If no messages space is available at the socket to hold
the message to be transmitted, then send normally blocks,
unless the socket has been placed in non-blocking I/O
mode. The select(2) call may be used to determine when it
is possible to send more data.
The flags parameter may include one or more of the follow-
ing:
#define MSG_OOB 0x1 /* process out-of-band data */
#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */
The flag MSG_OOB is used to send out-of-band data on sock-
ets that support this notion (e.g. SOCK_STREAM); the
underlying protocol must also support out-of-band data.
MSG_DONTROUTE is usually used only by diagnostic or rout-
ing programs.
See recv(2) for a description of the msghdr structure.
RETURN VALUES
The call returns the number of characters sent, or -1 if
an error occurred.
ERRORS
EBADF An invalid descriptor was specified.
ENOTSOCK
The argument s is not a socket.
EFAULT An invalid user space address was specified for a
parameter.
EMSGSIZE
The socket requires that message be sent atomi-
cally, and the size of the message to be sent made
this impossible.
EWOULDBLOCK
The socket is marked non-blocking and the
requested operation would block.
ENOBUFS The system was unable to allocate an internal
buffer. The operation may succeed when buffers
become available.
ENOBUFS The output queue for a network interface was full.
This generally indicates that the interface has
stopped sending, but may be caused by transient
congestion.
CONFORMING TO
4.4BSD, SVr4 (these function calls appeared in 4.2BSD).
The SVr4 versions docoment additional error conditions
EINVAL, EINTR, EMSGSIZE, ENOSR, ENOMEM.
SEE ALSO
fcntl(2), recv(2), select(2), getsockopt(2), socket(2),
write(2)
SEND(2) Linux Programmer's Manual SEND(2)
NAME
send, sendto, sendmsg - send a message from a socket
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
int send(int s, const void *msg, int len, unsigned int
flags);
int sendto(int s, const void *msg, int len, unsigned int
flags, const struct sockaddr *to, int tolen);
int sendmsg(int s, const struct msghdr *msg, unsigned int
flags);
DESCRIPTION
WARNING: This is a BSD man page. As of Linux 0.99.11,
sendmsg was not implemented.
Send, sendto, and sendmsg are used to transmit a message
to another socket. Send may be used only when the socket
is in a connected state, while sendto and sendmsg may be
used at any time.
The address of the target is given by to with tolen speci-
fying its size. The length of the message is given by
len. If the message is too long to pass atomically
through the underlying protocol, the error EMSGSIZE is
returned, and the message is not transmitted.
No indication of failure to deliver is implicit in a send.
Locally detected errors are indicated by a return value of
-1.
If no messages space is available at the socket to hold
the message to be transmitted, then send normally blocks,
unless the socket has been placed in non-blocking I/O
mode. The select(2) call may be used to determine when it
is possible to send more data.
The flags parameter may include one or more of the follow-
ing:
#define MSG_OOB 0x1 /* process out-of-band data */
#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */
The flag MSG_OOB is used to send out-of-band data on sock-
ets that support this notion (e.g. SOCK_STREAM); the
underlying protocol must also support out-of-band data.
MSG_DONTROUTE is usually used only by diagnostic or rout-
ing programs.
See recv(2) for a description of the msghdr structure.
RETURN VALUES
The call returns the number of characters sent, or -1 if
an error occurred.
ERRORS
EBADF An invalid descriptor was specified.
ENOTSOCK
The argument s is not a socket.
EFAULT An invalid user space address was specified for a
parameter.
EMSGSIZE
The socket requires that message be sent atomi-
cally, and the size of the message to be sent made
this impossible.
EWOULDBLOCK
The socket is marked non-blocking and the
requested operation would block.
ENOBUFS The system was unable to allocate an internal
buffer. The operation may succeed when buffers
become available.
ENOBUFS The output queue for a network interface was full.
This generally indicates that the interface has
stopped sending, but may be caused by transient
congestion.
CONFORMING TO
4.4BSD, SVr4 (these function calls appeared in 4.2BSD).
The SVr4 versions docoment additional error conditions
EINVAL, EINTR, EMSGSIZE, ENOSR, ENOMEM.
SEE ALSO
fcntl(2), recv(2), select(2), getsockopt(2), socket(2),
write(2)
SEND(2) Linux Programmer's Manual SEND(2)
NAME
send, sendto, sendmsg - send a message from a socket
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
int send(int s, const void *msg, int len, unsigned int
flags);
int sendto(int s, const void *msg, int len, unsigned int
flags, const struct sockaddr *to, int tolen);
int sendmsg(int s, const struct msghdr *msg, unsigned int
flags);
DESCRIPTION
WARNING: This is a BSD man page. As of Linux 0.99.11,
sendmsg was not implemented.
Send, sendto, and sendmsg are used to transmit a message
to another socket. Send may be used only when the socket
is in a connected state, while sendto and sendmsg may be
used at any time.
The address of the target is given by to with tolen speci-
fying its size. The length of the message is given by
len. If the message is too long to pass atomically
through the underlying protocol, the error EMSGSIZE is
returned, and the message is not transmitted.
No indication of failure to deliver is implicit in a send.
Locally detected errors are indicated by a return value of
-1.
If no messages space is available at the socket to hold
the message to be transmitted, then send normally blocks,
unless the socket has been placed in non-blocking I/O
mode. The select(2) call may be used to determine when it
is possible to send more data.
The flags parameter may include one or more of the follow-
ing:
#define MSG_OOB 0x1 /* process out-of-band data */
#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */
The flag MSG_OOB is used to send out-of-band data on sock-
ets that support this notion (e.g. SOCK_STREAM); the
underlying protocol must also support out-of-band data.
MSG_DONTROUTE is usually used only by diagnostic or rout-
ing programs.
See recv(2) for a description of the msghdr structure.
RETURN VALUES
The call returns the number of characters sent, or -1 if
an error occurred.
ERRORS
EBADF An invalid descriptor was specified.
ENOTSOCK
The argument s is not a socket.
EFAULT An invalid user space address was specified for a
parameter.
EMSGSIZE
The socket requires that message be sent atomi-
cally, and the size of the message to be sent made
this impossible.
EWOULDBLOCK
The socket is marked non-blocking and the
requested operation would block.
ENOBUFS The system was unable to allocate an internal
buffer. The operation may succeed when buffers
become available.
ENOBUFS The output queue for a network interface was full.
This generally indicates that the interface has
stopped sending, but may be caused by transient
congestion.
CONFORMING TO
4.4BSD, SVr4 (these function calls appeared in 4.2BSD).
The SVr4 versions docoment additional error conditions
EINVAL, EINTR, EMSGSIZE, ENOSR, ENOMEM.
SEE ALSO
fcntl(2), recv(2), select(2), getsockopt(2), socket(2),
write(2)
SERVICES(5) Linux Programmer's Manual SERVICES(5)
NAME
services - Internet network services list
DESCRIPTION
services is a plain ASCII file providing a mapping between
friendly textual names for internet services, and their
underlying assigned port numbers and protocol types. Every
networking program should look into this file to get the
port number (and protocol) for its service. The C library
routines getservent(3), getservbyname(3), getservby-
port(3), setservent(3), and endservent(3) support querying
this file from programs.
Port numbers are assigned by the IANA (Internet Assigned
Numbers Authority), and their current policy is to assign
both TCP and UDP protocols when assigning a port number.
Therefore, most entries will have two entries, even for
TCP only services.
Port numbers below 1024 (so-called 'low numbered' ports)
can only be bound to by root (see bind(2), tcp(7), and
udp(7).) This is so that clients connecting to low num-
bered ports can trust that the service running on the port
is the standard implementation, and not a rogue service
run by a user of the machine. Well-known port numbers
specified by the IANA are normally located in this root
only space.
The presence of an entry for a service in the services
file does not necessarily mean that the service is cur-
rently running on the machine. See inetd.conf(5) for the
configuration of Internet services offered. Note that not
all networking services are started by inetd(8), and so
won't appear in inetd.conf(5). In particular, news (NNTP)
and mail (SMTP) servers are often initialised from the
system boot scripts.
The location of the services file is defined by _PATH_SER-
VICES in /usr/include/netdb.h. This is usually set to
/etc/services.
Each line describes one service, and is of the form:
service-name port/protocol [aliases ...]
where:
service-name
is the friendly name the service is known by and
looked up under. It is case sensitive. Often,
the client program is named after the service-
name.
port is the port number (in decimal) to use for this
service.
protocol is the type of protocol to be used. This field
should match an entry in the protocols(5) file.
Typical values include tcp and udp.
aliases is an optional space or tab separated list of
other names for this service (but see the BUGS
section below). Again, the names are case sensi-
tive.
Either spaces or tabs may be used to separate the fields.
Comments are started by the hash sign (#) and continue
until the end of the line. Blank lines are skipped.
The service-name should begin in the first column of the
file, since leading spaces are not stripped. service-
names can be any printable characters excluding space and
tab, however, a conservative choice of characters should
be used to minimise inter-operability problems. Eg: a-z,
0-9, and hyphen (-) would seem a sensible choice.
Lines not matching this format should not be present in
the file. (Currently, they are silently skipped by getser-
vent(3), getservbyname(3), and getservbyport(3). However,
this behaviour should not be relied on.)
As a backwards compatibility feature, the slash (/)
between the port number and protocol name can in fact be
either a slash or a comma (,). Use of the comma in modern
installations is depreciated.
This file might be distributed over a network using a net-
work-wide naming service like Yellow Pages/NIS or
BIND/Hesiod.
A sample services file might look like this:
netstat 15/tcp
qotd 17/tcp quote
msp 18/tcp # message send protocol
msp 18/udp # message send protocol
chargen 19/tcp ttytst source
chargen 19/udp ttytst source
ftp 21/tcp
# 22 - unassigned
telnet 23/tcp
BUGS
There is a maximum of 35 aliases, due to the way the get-
servent(3) code is written.
Lines longer than BUFSIZ (currently 1024) characters will
be ignored by getservent(3), getservbyname(3), and get-
servbyport(3). However, this will also cause the next
line to be mis-parsed.
FILES
/etc/services
The Internet network services list
/usr/include/netdb.h
Definition of _PATH_SERVICES
SEE ALSO
getservent(3), getservbyname(3), getservbyport(3), setser-
vent(3), endservent(3), protocols(5), listen(2),
inetd.conf(5), inetd(8).
Assigned Numbers RFC, most recently RFC 1700, (AKA
STD0002)
Guide to Yellow Pages Service
Guide to BIND/Hesiod Service
GETDOMAINNAME(2) Linux Programmer's Manual GETDOMAINNAME(2)
NAME
getdomainname, setdomainname - get/set domain name
SYNOPSIS
#include <unistd.h>
int getdomainname(char *name, size_t len);
int setdomainname(const char *name, size_t len);
DESCRIPTION
These functions are used to access or to change the domain
name of the current processor.
RETURN VALUE
On success, zero is returned. On error, -1 is returned,
and errno is set appropriately.
ERRORS
EINVAL For getdomainname, name points to NULL or name is
longer than len.
EPERM For setdomainname, the caller was not the supe-
ruser.
EINVAL For setdomainname, len was too long.
CONFORMING TO
POSIX does not specify these calls.
BUGS
getdomainname is not compliant with other implementations,
since they always return len bytes, even if name is
longer. Linux, however, returns EINVAL in this case (as
of DLL 4.4.1 libraries).
NOTES
Under Linux, getdomainname is implemented at the library
level by calling uname(2).
SEE ALSO
gethostname(2), sethostname(2), uname(2)
GETHOSTBYNAME(3) Linux Programmer's Manual GETHOSTBYNAME(3)
NAME
gethostbyname, gethostbyaddr, sethostent, endhostent, her-
ror - get network host entry
SYNOPSIS
#include <netdb.h>
extern int h_errno;
struct hostent *gethostbyname(const char *name);
#include <sys/socket.h> /* for AF_INET */
struct hostent *gethostbyaddr(const char *addr, int len, int type);
void sethostent(int stayopen);
void endhostent(void);
void herror(const char *s);
DESCRIPTION
The gethostbyname() function returns a structure of type
hostent for the given host name. Here name is either a
host name, or an IPv4 address in standard dot notation, or
an IPv6 address in colon (and possibly dot) notation. (See
RFC 1884 for the description of IPv6 addresses.) If name
doesn't end in a dot and the environment variable HOSTAL-
IASES is set, the alias file pointed to by HOSTALIASES
will first be searched for name. (See hostname(7) for the
file format.) The current domain and its parents are
searched unless name ends in a dot.
The gethostbyaddr() function returns a structure of type
hostent for the given host address addr of length len and
address type type. The only valid address type is cur-
rently AF_INET.
The sethostent() function specifies, if stayopen is true
(1), that a connected TCP socket should be used for the
name server queries and that the connection should remain
open during successive queries. Otherwise, name server
queries will use UDP datagrams.
The endhostent() function ends the use of a TCP connection
for name server queries.
The herror() function prints the error message associated
with the current value of h_errno on stderr.
The domain name queries carried out by gethostbyname() and
gethostbyaddr() use a combination of any or all of the
name server named(8), a broken out line from /etc/hosts,
and the Network Information Service (NIS or YP), depending
upon the contents of the order line in /etc/host.conf.
(See resolv+(8)). The default action is to query
named(8), followed by /etc/hosts.
The hostent structure is defined in <netdb.h> as follows:
struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses */
}
#define h_addr h_addr_list[0] /* for backward compatibility */
The members of the hostent structure are:
h_name The official name of the host.
h_aliases
A zero-terminated array of alternative names for
the host.
h_addrtype
The type of address; always AF_INET at present.
h_length
The length of the address in bytes.
h_addr_list
A zero-terminated array of network addresses for
the host in network byte order.
h_addr The first address in h_addr_list for backward com-
patibility.
RETURN VALUE
The gethostbyname() and gethostbyaddr() functions return
the hostent structure or a NULL pointer if an error
occurs. On error, the h_errno variable holds an error
number.
ERRORS
The variable h_errno can have the following values:
HOST_NOT_FOUND
The specified host is unknown.
NO_ADDRESS
The requested name is valid but does not have an IP
address.
NO_RECOVERY
A non-recoverable name server error occurred.
TRY_AGAIN
A temporary error occurred on an authoritative name
server. Try again later.
FILES
/etc/host.conf
resolver configuration file
/etc/hosts
host database file
CONFORMING TO
BSD 4.3
SEE ALSO
resolver(3), hosts(5), hostname(7), resolv+(8), named(8)
GETHOSTNAME(2) Linux Programmer's Manual GETHOSTNAME(2)
NAME
gethostname, sethostname - get/set host name
SYNOPSIS
#include <unistd.h>
int gethostname(char *name, size_t len);
int sethostname(const char *name, size_t len);
DESCRIPTION
These functions are used to access or to change the host
name of the current processor.
RETURN VALUE
On success, zero is returned. On error, -1 is returned,
and errno is set appropriately.
ERRORS
EINVAL len is negative or, for sethostname, len is larger
than the maximum allowed size, or, for gethostname
on Linux/i386, len is smaller than the actual size.
EPERM For sethostname, the caller was not the superuser.
EFAULT name is an invalid address.
CONFORMING TO
SVr4, 4.4BSD (this function first appeared in 4.2BSD).
POSIX.1 does not define these functions, but ISO/IEC
9945-1:1990 mentions them in B.4.4.1.
BUGS
Some other implementations of gethostname successfully
return len bytes even if name is longer. Linux/Alpha com-
plies with this behaviour. Linux/i386, however, returns
EINVAL in this case (as of DLL 4.6.27 libraries).
NOTES
Under Linux/Alpha, gethostname is a system call. Under
Linux/i386, gethostname is implemented at the library
level by calling uname(2).
SEE ALSO
getdomainname(2), setdomainname(2), uname(2)
GETNETENT(3) Linux Programmer's Manual GETNETENT(3)
NAME
getnetent, getnetbyname, getnetbyaddr, setnetent, endne-
tent - get network entry
SYNOPSIS
#include <netdb.h>
struct netent *getnetent(void);
struct netent *getnetbyname(const char *name);
struct netent *getnetbyaddr(long net, int type);
void setnetent(int stayopen);
void endnetent(void);
DESCRIPTION
The getnetent() function reads the next line from the file
/etc/networks and returns a structure netent containing
the broken out fields from the line. The /etc/networks
file is opened if necessary.
The getnetbyname() function returns a netent structure for
the line from /etc/networks that matches the network name.
The getnetbyaddr() function returns a netent structure for
the line that matches the network number net of type type.
The setnetent() function opens and rewinds the /etc/net-
works file. If stayopen is true (1), then the file will
not be closed between calls to getnetbyname() and getnet-
byaddr().
The endservent() function closes /etc/networks.
The netent structure is defined in <netdb.h> as follows:
struct netent {
char *n_name; /* official network name */
char **n_aliases; /* alias list */
int n_addrtype; /* net address type */
unsigned long int n_net; /* network number */
}
The members of the netent structure are:
n_name The official name of the network.
n_aliases
A zero terminated list of alternative names for the
network.
n_addrtype
The type of the network number; always AF_INET.
n_net The network number in host byte order.
RETURN VALUE
The getnetent(), getnetbyname() and getnetbyaddr() func-
tions return the netent structure, or a NULL pointer if an
error occurs or the end of the file is reached.
FILES
/etc/networks networks database file
CONFORMING TO
BSD 4.3
SEE ALSO
getprotoent(3), getservent(3), networks(5)
GETPROTOENT(3) Linux Programmer's Manual GETPROTOENT(3)
NAME
getprotoent, getprotobyname, getprotobynumber, setpro-
toent, endprotoent - get protocol entry
SYNOPSIS
#include <netdb.h>
struct protoent *getprotoent(void);
struct protoent *getprotobyname(const char *name);
struct protoent *getprotobynumber(int proto);
void setprotoent(int stayopen);
void endprotoent(void);
DESCRIPTION
The getprotoent() function reads the next line from the
file /etc/protocols and returns a structure protoent con-
taining the broken out fields from the line. The
/etc/protocols file is opened if necessary.
The getprotobyname() function returns a protoent structure
for the line from /etc/protocols that matches the protocol
name name.
The getprotobynumber() function returns a protoent struc-
ture for the line that matches the protocol number number.
The setprotoent() function opens and rewinds the /etc/pro-
tocols file. If stayopen is true (1), then the file will
not be closed between calls to getprotobyname() or getpro-
tobynumber().
The endprotoent() function closes /etc/protocols.
The protoent structure is defined in <netdb.h> as follows:
struct protoent {
char *p_name; /* official protocol name */
char **p_aliases; /* alias list */
int p_proto; /* protocol number */
}
The members of the protoent structure are:
p_name The official name of the protocol.
p_aliases
A zero terminated list of alternative names for the
protocol.
p_proto
The protocol number.
RETURN VALUE
The getprotoent(), getprotobyname() and getprotobynumber()
functions return the protoent structure, or a NULL pointer
if an error occurs or the end of the file is reached.
FILES
/etc/protocols
protocol database file
CONFORMING TO
BSD 4.3
SEE ALSO
getservent(3), getnetent(3), protocols(5)
GETSERVENT(3) Linux Programmer's Manual GETSERVENT(3)
NAME
getservent, getservbyname, getservbyport, setservent, end-
servent - get service entry
SYNOPSIS
#include <netdb.h>
struct servent *getservent(void);
struct servent *getservbyname(const char *name, const char *proto);
struct servent *getservbyport(int port, const char *proto);
void setservent(int stayopen);
void endservent(void);
DESCRIPTION
The getservent() function reads the next line from the
file /etc/services and returns a structure servent con-
taining the broken out fields from the line. The
/etc/services file is opened if necessary.
The getservbyname() function returns a servent structure
for the line from /etc/services that matches the service
name using protocol proto.
The getservbyport() function returns a servent structure
for the line that matches the port port given in network
byte order using protocol proto.
The setservent() function opens and rewinds the /etc/ser-
vices file. If stayopen is true (1), then the file will
not be closed between calls to getservbyname() and get-
servbyport().
The endservent() function closes /etc/services.
The servent structure is defined in <netdb.h> as follows:
struct servent {
char *s_name; /* official service name */
char **s_aliases; /* alias list */
int s_port; /* port number */
char *s_proto; /* protocol to use */
}
The members of the servent structure are:
s_name The official name of the service.
s_aliases
A zero terminated list of alternative names for the
service.
s_port The port number for the service given in network
byte order.
s_proto
The name of the protocol to use with this service.
RETURN VALUE
The getservent(), getservbyname() and getservbyport()
functions return the servent structure, or a NULL pointer
if an error occurs or the end of the file is reached.
FILES
/etc/services
services database file
CONFORMING TO
BSD 4.3
SEE ALSO
getprotoent(3), getnetent(3), services(5)
GETSOCKOPT(2) Linux Programmer's Manual GETSOCKOPT(2)
NAME
getsockopt, setsockopt - get and set options on sockets
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
int getsockopt(int s, int level, int optname, void *opt-
val, int *optlen);
int setsockopt(int s, int level, int optname, const void
*optval, int optlen);
DESCRIPTION
Getsockopt and setsockopt manipulate the options associ-
ated with a socket. Options may exist at multiple proto-
col levels; they are always present at the uppermost
socket level.
When manipulating socket options the level at which the
option resides and the name of the option must be speci-
fied. To manipulate options at the socket level, level is
specified as SOL_SOCKET. To manipulate options at any
other level the protocol number of the appropriate proto-
col controlling the option is supplied. For example, to
indicate that an option is to be interpreted by the TCP
protocol, level should be set to the protocol number of
TCP; see getprotoent(3).
The parameters optval and optlen are used to access option
values for setsockopt. For getsockopt they identify a
buffer in which the value for the requested option(s) are
to be returned. For getsockopt, optlen is a value-result
parameter, initially containing the size of the buffer
pointed to by optval, and modified on return to indicate
the actual size of the value returned. If no option value
is to be supplied or returned, optval may be NULL.
Optname and any specified options are passed uninterpreted
to the appropriate protocol module for interpretation.
The include file <sys/socket.h> contains definitions for
socket level options, described below. Options at other
protocol levels vary in format and name; consult the
appropriate entries in section 4 of the manual.
Most socket-level options utilize an int parameter for
optval. For setsockopt, the parameter should be non-zero
to enable a boolean option, or zero if the option is to be
disabled. SO_LINGER uses a struct linger parameter,
defined in <linux/socket.h>, which specifies the desired
state of the option and the linger interval (see below).
SO_SNDTIMEO and SO_RCVTIMEO use a struct timeval parame-
ter, defined in <sys/time.h>.
The following options are recognized at the socket level.
Except as noted, each may be examined with getsockopt and
set with setsockopt.
SO_DEBUG
enables recording of debugging information
SO_REUSEADDR
enables local address reuse
SO_KEEPALIVE
enables keep connections alive
SO_DONTROUTE
enables routing bypass for outgoing messages
SO_LINGER
linger on close if data present
SO_BROADCAST
enables permission to transmit broadcast messages
SO_OOBINLINE
enables reception of out-of-band data in band
SO_SNDBUF
set buffer size for output
SO_RCVBUF
set buffer size for input
SO_SNDLOWAT
set minimum count for output
SO_RCVLOWAT
set minimum count for input
SO_SNDTIMEO
get timeout value for output (get only)
SO_RCVTIMEO
get timeout value for input (get only)
SO_TYPE get the type of the socket (get only)
SO_ERROR
get and clear error on the socket (get only)
SO_DEBUG enables debugging in the underlying protocol mod-
ules. SO_REUSEADDR indicates that the rules used in vali-
dating addresses supplied in a bind(2) call should allow
reuse of local addresses. SO_KEEPALIVE enables the peri-
odic transmission of messages on a connected socket.
Should the connected party fail to respond to these
messages, the connection is considered broken and pro-
cesses using the socket are notified via a SIGPIPE signal
when attempting to send data. SO_DONTROUTE indicates that
outgoing messages should bypass the standard routing
facilities. Instead, messages are directed to the appro-
priate network interface according to the network portion
of the destination address.
SO_LINGER controls the action taken when unsent messages
are queued on socket and a close(2) is performed. If the
socket promises reliable delivery of data and SO_LINGER is
set, the system will block the process on the close
attempt until it is able to transmit the data or until it
decides it is unable to deliver the information (a timeout
period, termed the linger interval, is specified in the
setsockopt call when SO_LINGER is requested). If
SO_LINGER is disabled and a close is issued, the system
will process the close in a manner that allows the process
to continue as quickly as possible.
The linger structure is defined in <linux/socket.h> as
follows:
struct linger {
int l_onoff; /* Linger active */
int l_linger; /* How long to linger for */
};
l_onoff indicates wether to linger or not. If it is set to
1 then l_linger contains the time in hundredths of seconds
how long the process should linger to complete the close.
If l_onoff is set to zero the process returns immediately.
The option SO_BROADCAST requests permission to send broad-
cast datagrams on the socket. Broadcast was a privileged
operation in earlier versions of the system. With proto-
cols that support out-of-band data, the SO_OOBINLINE
option requests that out-of-band data be placed in the
normal data input queue as received; it will then be
accessible with recv or read calls without the MSG_OOB
flag. Some protocols always behave as if this option is
set. SO_SNDBUF and SO_RCVBUF are options to adjust the
normal buffer sizes allocated for output and input
buffers, respectively. The buffer size may be increased
for high-volume connections, or may be decreased to limit
the possible backlog of incoming data. The system places
an absolute limit on these values.
SO_SNDLOWAT is an option to set the minimum count for out-
put operations. Most output operations process all of the
data supplied by the call, delivering data to the protocol
for transmission and blocking as necessary for flow con-
trol. Nonblocking output operations will process as much
data as permitted subject to flow control without
blocking, but will process no data if flow control does
not allow the smaller of the low water mark value or the
entire request to be processed. A select(2) operation
testing the ability to write to a socket will return true
only if the low water mark amount could be processed. The
default value for SO_SNDLOWAT is set to a convenient size
for network efficiency, often 1024.
SO_RCVLOWAT is an option to set the minimum count for
input operations. In general, receive calls will block
until any (non-zero) amount of data is received, then
return with smaller of the amount available or the amount
requested. The default value for SO_RCVLOWAT is 1. If
SO_RCVLOWAT is set to a larger value, blocking receive
calls normally wait until they have received the smaller
of the low water mark value or the requested amount.
Receive calls may still return less than the low water
mark if an error occurs, a signal is caught, or the type
of data next in the receive queue is different than that
returned.
SO_SNDTIMEO is an option to get the timeout value for out-
put operations. (It can be used with getsockopt only).
It returns a struct timeval parameter with the number of
seconds and microseconds used to limit waits for output
operations to complete. If a send operation has blocked
for this much time, it returns with a partial count or
with the error EWOULDBLOCK if no data were sent. In the
current implementation, this timer is restarted each time
additional data are delivered to the protocol, implying
that the limit applies to output portions ranging in size
from the low water mark to the high water mark for output.
SO_RCVTIMEO is an option to get the timeout value for
input operations. (It can be used with getsockopt only).
It returns a struct timeval parameter with the number of
seconds and microseconds used to limit waits for input
operations to complete. In the current implementation,
this timer is restarted each time additional data are
received by the protocol, and thus the limit is in effect
an inactivity timer. If a receive operation has been
blocked for this much time without receiving additional
data, it returns with a short count or with the error
EWOULDBLOCK if no data were received.
Finally, also SO_TYPE and SO_ERROR are options used only
with getsockopt. SO_TYPE returns the type of the socket,
such as SOCK_STREAM; it is useful for servers that inherit
sockets on startup. SO_ERROR returns any pending error on
the socket and clears the error status. It may be used to
check for asynchronous errors on connected datagram sock-
ets or for other asynchronous errors.
RETURN VALUE
On success, zero is returned. On error, -1 is returned,
and errno is set appropriately.
ERRORS
EBADF The argument s is not a valid descriptor.
ENOTSOCK
The argument s is a file, not a socket.
ENOPROTOOPT
The option is unknown at the level indicated.
EFAULT The address pointed to by optval is not in a valid
part of the process address space. For getsock-
opt, this error may also be returned if optlen is
not in a valid part of the process address space.
CONFORMING TO
SVr4, 4.4BSD (these system calls first appeared in
4.2BSD). SVr4 documents additional ENOMEM and ENOSR error
codes, but does not document the SO_SNDLOWAT, SO_RCVLOWAT,
SO_SNDTIMEO, SO_RCVTIMEO options
BUGS
Several of the socket options should be handled at lower
levels of the system.
SEE ALSO
ioctl(2), socket(2), getprotoent(3), protocols(5)
SHUTDOWN(2) Linux Programmer's Manual SHUTDOWN(2)
NAME
shutdown - shut down part of a full-duplex connection
SYNOPSIS
#include <sys/socket.h>
int shutdown(int s, int how);
DESCRIPTION
The shutdown call causes all or part of a full-duplex con-
nection on the socket associated with s to be shut down.
If how is 0, further receives will be disallowed. If how
is 1, further sends will be disallowed. If how is 2, fur-
ther sends and receives will be disallowed.
RETURN VALUE
On success, zero is returned. On error, -1 is returned,
and errno is set appropriately.
ERRORS
EBADF s is not a valid descriptor.
ENOTSOCK
s is a file, not a socket.
ENOTCONN
The specified socket is not connected.
CONFORMING TO
4.4BSD (the shutdown function call first appeared in
4.2BSD).
SEE ALSO
connect(2), socket(2)
SOCKET(2) Linux Programmer's Manual SOCKET(2)
NAME
socket - create an endpoint for communication
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
int socket(int domain, int type, int protocol);
SNAPSHOT DOCUMENTATION:
Click here (or here for bigger text)
to trace through a debugging setup that
demonstrates many of the socket related system calls.
DESCRIPTION
Socket creates an endpoint for communication and returns a
descriptor.
The domain parameter specifies a communications domain
within which communication will take place; this selects
the protocol family which should be used. These families
are defined in the include file sys/socket.h. The cur-
rently understood formats are
AF_UNIX (UNIX internal protocols)
AF_INET (ARPA Internet protocols)
AF_ISO (ISO protocols)
AF_NS (Xerox Network Systems protocols)
AF_IMPLINK
(IMP "host at IMP" link layer)
The socket has the indicated type, which specifies the
semantics of communication. Currently defined types are:
SOCK_STREAM
SOCK_DGRAM
SOCK_RAW
SOCK_SEQPACKET
SOCK_RDM
A SOCK_STREAM type provides sequenced, reliable, two-way
connection based byte streams. An out-of-band data trans-
mission mechanism may be supported. A SOCK_DGRAM socket
supports datagrams (connectionless, unreliable messages of
a fixed (typically small) maximum length). A SOCK_SEQ-
PACKET socket may provide a sequenced, reliable, two-way
connection-based data transmission path for datagrams of
fixed maximum length; a consumer may be required to read
an entire packet with each read system call. This facil-
ity is protocol specific, and presently implemented only
for AF_NS. SOCK_RAW sockets provide access to internal
network protocols and interfaces. The types SOCK_RAW,
which is available only to the super-user, and SOCK_RDM,
which is planned, but not yet implemented, are not
described here.
The protocol specifies a particular protocol to be used
with the socket. Normally only a single protocol exists
to support a particular socket type within a given proto-
col family. However, it is possible that many protocols
may exist, in which case a particular protocol must be
specified in this manner. The protocol number to use is
particular to the "communication domain" in which communi-
cation is to take place; see protocols(5).
Sockets of type SOCK_STREAM are full-duplex byte streams,
similar to pipes. A stream socket must be in a connected
state before any data may be sent or received on it. A
connection to another socket is created with a connect(2)
call. Once connected, data may be transferred using
read(2) and write(2) calls or some variant of the send(2)
and recv(2) calls. When a session has been completed a
close(2) may be performed. Out-of-band data may also be
transmitted as described in send(2) and received as
described in recv(2).
The communications protocols used to implement a
SOCK_STREAM insure that data is not lost or duplicated.
If a piece of data for which the peer protocol has buffer
space cannot be successfully transmitted within a reason-
able length of time, then the connection is considered
broken and calls will indicate an error with -1 returns
and with ETIMEDOUT as the specific code in the global
variable errno. The protocols optionally keep sockets
warm by forcing transmissions roughly every minute in the
absence of other activity. An error is then indicated if
no response can be elicited on an otherwise idle connec-
tion for a extended period (e.g. 5 minutes). A SIGPIPE
signal is raised if a process sends on a broken stream;
this causes naive processes, which do not handle the sig-
nal, to exit.
SOCK_SEQPACKET sockets employ the same system calls as
SOCK_STREAM sockets. The only difference is that read(2)
calls will return only the amount of data requested, and
any remaining in the arriving packet will be discarded.
SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams
to correspondents named in send(2) calls. Datagrams are
generally received with recvfrom(2), which returns the
next datagram with its return address.
An fcntl(2) call can be used to specify a process group to
receive a SIGURG signal when the out-of-band data arrives.
It may also enable non-blocking I/O and asynchronous noti-
fication of I/O events via SIGIO.
The operation of sockets is controlled by socket level
options. These options are defined in the file
sys/socket.h. Setsockopt(2) and getsockopt(2) are used to
set and get options, respectively.
RETURN VALUES
A -1 is returned if an error occurs, otherwise the return
value is a descriptor referencing the socket.
ERRORS
EPROTONOSUPPORT
The protocol type or the specified protocol is not
supported within this domain.
EMFILE The per-process descriptor table is full.
ENFILE The system file table is full.
EACCES Permission to create a socket of the specified
type and/or protocol is denied.
ENOBUFS Insufficient buffer space is available. The
socket cannot be created until sufficient
resources are freed.
CONFORMING TO
4.4BSD (the socket function call appeared in 4.2BSD). Gen-
erally portable to/from non-BSD systems supporting clones
of the BSD socket layer (including System V variants).
SEE ALSO
accept(2), bind(2), connect(2), getprotoent(3), getsock-
name(2), getsockopt(2), ioctl(2), listen(2), read(2),
recv(2), select(2), send(2), shutdown(2), socketpair(2),
write(2)
"An Introductory 4.3 BSD Interprocess Communication Tuto-
rial" is reprinted in UNIX Programmer's Supplementary Doc-
uments Volume 1
"BSD Interprocess Communication Tutorial" is reprinted in
UNIX Programmer's Supplementary Documents Volume 1
WRITE(2) System calls WRITE(2)
NAME
write - write to a file descriptor
SYNOPSIS
#include <unistd.h>
ssize_t write(int fd, const void *buf, size_t count);
DESCRIPTION
write writes up to count bytes to the file referenced by
the file descriptor fd from the buffer starting at buf.
POSIX requires that a read() which can be proved to occur
after a write() has returned returns the new data. Note
that not all file systems are POSIX conforming.
RETURN VALUE
On success, the number of bytes written are returned (zero
indicates nothing was written). On error, -1 is returned,
and errno is set appropriately. If count is zero and the
file descriptor refers to a regular file, 0 will be
returned without causing any other effect. For a special
file, the results are not portable.
ERRORS
EBADF fd is not a valid file descriptor or is not open
for writing.
EINVAL fd is attached to an object which is unsuitable for
writing.
EFAULT buf is outside your accessible address space.
EPIPE fd is connected to a pipe or socket whose reading
end is closed. When this happens the writing pro-
cess will receive a SIGPIPE signal; if it catches,
blocks or ignores this the error EPIPE is returned.
EAGAIN Non-blocking I/O has been selected using O_NONBLOCK
and there was no room in the pipe or socket con-
nected to fd to write the data immediately.
EINTR The call was interrupted by a signal before any
data was written.
ENOSPC The device containing the file referred to by fd
has no room for the data.
EIO A low-level I/O error occurred while modifying the
inode.
Other errors may occur, depending on the object connected
to fd.
CONFORMING TO
SVr4, SVID, POSIX, X/OPEN, 4.3BSD. SVr4 documents addi-
tional error conditions EDEADLK, EFBIG, ENOLCK, ENOLNK,
ENOSR, ENXIO, EPIPE, or ERANGE. Under SVr4 a write may be
interrupted and return EINTR at any point, not just before
any data is written.
SEE ALSO
open(2), read(2), fcntl(2), close(2), lseek(2), select(2),
ioctl(2), fsync(2), fwrite(3).
man2html.pl Version 1.2, Copyright 1997, 1998
by Richard Dawe
Document rewritten (colours and new formatting
features) by Sabin-Corneliu
Buraga.
Last revision: 19 September 1999