'\" te
.\" Copyright (c) 1983, Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement  specifies the terms and conditions for redistribution.  Copyright 1989 AT&T.  Copyright (c) 2007, Sun Microsystems, Inc.
.\" All Rights Reserved.
.TH GETSERVBYNAME 3SOCKET "Jan 31, 2007"
.SH NAME
getservbyname, getservbyname_r, getservbyport, getservbyport_r, getservent,
getservent_r, setservent, endservent \- get service entry
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
#include <netdb.h>

\fBstruct servent *\fR\fBgetservbyname\fR(\fBconst char *\fR\fIname\fR, \fBconst char *\fR\fIproto\fR);
.fi

.LP
.nf
\fBstruct servent *\fR\fBgetservbyname_r\fR(\fBconst char *\fR\fIname\fR, \fBconst char *\fR\fIproto\fR,
     \fBstruct servent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR);
.fi

.LP
.nf
\fBstruct servent *\fR\fBgetservbyport\fR(\fBint\fR \fIport\fR, \fBconst char *\fR\fIproto\fR);
.fi

.LP
.nf
\fBstruct servent *\fR\fBgetservbyport_r\fR(\fBint\fR \fIport\fR, \fBconst char *\fR\fIproto\fR,
     \fBstruct servent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR);
.fi

.LP
.nf
\fBstruct servent *\fR\fBgetservent\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBstruct servent *\fR\fBgetservent_r\fR(\fBstruct servent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR,
     \fBint\fR \fIbuflen\fR);
.fi

.LP
.nf
\fBint\fR \fBsetservent\fR(\fBint\fR \fIstayopen\fR);
.fi

.LP
.nf
\fBint\fR \fBendservent\fR(\fBvoid\fR);
.fi

.SH DESCRIPTION
.LP
These functions are used to obtain entries for Internet services.  An entry may
come from any of the sources for \fBservices\fR specified in the
\fB/etc/nsswitch.conf\fR file. See \fBnsswitch.conf\fR(4).
.sp
.LP
The \fBgetservbyname()\fR and \fBgetservbyport()\fR functions sequentially
search from the  beginning of the file until a matching protocol  name or port
number is found, or until end-of-file  is  encountered.  If a protocol  name is
also supplied (non-null), searches must also match the protocol.
.sp
.LP
The \fBgetservbyname()\fR function searches for an entry with the Internet
service name specified by the \fIname\fR parameter.
.sp
.LP
The \fBgetservbyport()\fR function searches for an entry with the Internet port
number \fIport\fR.
.sp
.LP
All addresses are returned in network order. In order to  interpret the
addresses, \fBbyteorder\fR(3C) must be used for byte order conversion. The
string \fIproto\fR is used by both \fBgetservbyname()\fR and
\fBgetservbyport()\fR to restrict the search to entries with the specified
protocol. If \fIproto\fR is \fINULL\fR, entries with any protocol can be
returned.
.sp
.LP
The functions \fBsetservent()\fR, \fBgetservent()\fR, and \fBendservent()\fR
are used to enumerate entries from the services database.
.sp
.LP
The \fBsetservent()\fR function sets (or resets) the enumeration to the
beginning of the set of service entries. This function should be called before
the first call to \fBgetservent()\fR. Calls to the functions
\fBgetservbyname()\fR and \fBgetservbyport()\fR leave the enumeration position
in an indeterminate state.   If the \fIstayopen\fR flag is non-zero, the system
may keep allocated resources such as open file descriptors until a subsequent
call to \fBendservent()\fR.
.sp
.LP
The \fBgetservent()\fR function reads the next line of the file, opening the
file if necessary. \fBgetservent()\fR opens and rewinds the file. If  the
\fIstayopen\fR flag is non-zero, the net data base will not be closed after
each call to \fBgetservent()\fR (either directly, or indirectly through one of
the other "getserv"calls).
.sp
.LP
Successive calls to \fBgetservent()\fR return either successive entries or
\fINULL\fR, indicating the end of the enumeration.
.sp
.LP
The \fBendservent()\fR function closes the file. The \fBendservent()\fR
function can be called to indicate that the caller expects to do no further
service entry retrieval operations; the system can then deallocate resources it
was using.  It is still allowed, but possibly less efficient, for the process
to call more service entry retrieval functions after calling
\fBendservent()\fR.
.SS "Reentrant Interfaces"
.LP
The functions \fBgetservbyname()\fR, \fBgetservbyport()\fR, and
\fBgetservent()\fR use static storage that is re-used in each call, making
these functions unsafe for use in multithreaded applications.
.sp
.LP
The functions \fBgetservbyname_r()\fR, \fBgetservbyport_r()\fR, and
\fBgetservent_r()\fR provide reentrant interfaces for these operations.
.sp
.LP
Each reentrant interface performs the same operation as its non-reentrant
counterpart, named by removing the  "\fB_r\fR" suffix.  The reentrant
interfaces, however, use buffers supplied by the caller to store returned
results, and  are safe for use in both single-threaded and multithreaded
applications.
.sp
.LP
Each reentrant interface takes the same parameters as its non-reentrant
counterpart, as well as the following additional parameters. The parameter
\fIresult\fR must be a pointer to a \fBstruct servent\fR structure allocated by
the caller.  On successful completion, the function returns the service entry
in this structure. The parameter \fIbuffer\fR must be a pointer to a buffer
supplied by the caller.  This buffer is used as storage space for the service
entry data.  All of the pointers within the returned \fBstruct servent\fR
\fIresult\fR point to data stored within this buffer.  See the RETURN VALUES
section of this manual page. The buffer must be large enough to hold all of the
data associated with the service entry. The parameter \fIbuflen\fR should give
the size in bytes of the buffer indicated by \fIbuffer\fR.
.sp
.LP
For enumeration in multithreaded applications, the position within the
enumeration is a process-wide property shared by all threads. The
\fBsetservent()\fR function can be used in a multithreaded application but
resets the enumeration position for all threads.  If multiple threads
interleave calls to \fBgetservent_r()\fR, the threads will enumerate disjoint
subsets of the service database.
.sp
.LP
Like their non-reentrant counterparts, \fBgetservbyname_r()\fR and
\fBgetservbyport_r()\fR leave the enumeration position in an indeterminate
state.
.SH RETURN VALUES
.LP
Service entries are represented by the \fBstruct servent\fR structure defined
in <\fBnetdb.h\fR>:
.sp
.in +2
.nf
struct  servent {
    char	*s_name;		      /* official name of service */
    char	**s_aliases;		   /* alias list */
    int	s_port;			   /* port service resides at */
    char	*s_proto;		      /* protocol to use */
};
.fi
.in -2

.sp
.LP
The members of this structure are:
.sp
.ne 2
.na
\fB\fBs_name\fR\fR
.ad
.RS 13n
The official name of the service.
.RE

.sp
.ne 2
.na
\fB\fBs_aliases\fR\fR
.ad
.RS 13n
A zero terminated list of alternate names for the service.
.RE

.sp
.ne 2
.na
\fB\fBs_port\fR\fR
.ad
.RS 13n
The port number at which  the  service  resides.  Port  numbers  are
returned  in  network  byte order.
.RE

.sp
.ne 2
.na
\fB\fBs_proto\fR\fR
.ad
.RS 13n
The name of  the  protocol  to  use when contacting the service
.RE

.sp
.LP
The functions \fBgetservbyname()\fR, \fBgetservbyname_r()\fR,
\fBgetservbyport()\fR, and \fBgetservbyport_r()\fR each return a pointer to a
\fBstruct servent\fR if they successfully locate the requested entry; otherwise
they return \fINULL\fR.
.sp
.LP
The functions \fBgetservent()\fR and \fBgetservent_r()\fR each return a pointer
to a \fBstruct servent\fR if they successfully enumerate an entry; otherwise
they return \fINULL,\fR indicating the end of the enumeration.
.sp
.LP
The functions \fBgetservbyname()\fR, \fBgetservbyport()\fR, and
\fBgetservent()\fR use static storage, so returned data must be copied before a
subsequent call to any of these functions if the data is to be saved.
.sp
.LP
When the pointer returned by the reentrant functions \fBgetservbyname_r()\fR,
\fBgetservbyport_r()\fR, and \fBgetservent_r()\fR is non-null, it is always
equal to the \fIresult\fR pointer that was supplied by the caller.
.SH ERRORS
.LP
The reentrant functions \fBgetservbyname_r()\fR, \fBgetservbyport_r()\fR, and
\fBgetservent_r()\fR return \fINULL\fR and set \fBerrno\fR to \fBERANGE\fR if
the length of the buffer supplied by caller is not large enough to store the
result.  See \fBIntro\fR(2) for the proper usage and interpretation of
\fBerrno\fR in multithreaded applications.
.SH FILES
.ne 2
.na
\fB\fB/etc/services\fR\fR
.ad
.RS 22n
Internet network services
.RE

.sp
.ne 2
.na
\fB\fB/etc/netconfig\fR\fR
.ad
.RS 22n
network configuration file
.RE

.sp
.ne 2
.na
\fB\fB/etc/nsswitch.conf\fR\fR
.ad
.RS 22n
configuration file for the name-service switch
.RE

.SH ATTRIBUTES
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	T{
See "Reentrant Interfaces" in \fBDESCRIPTION\fR.
T}
.TE

.SH SEE ALSO
.LP
\fBIntro\fR(2), \fBIntro\fR(3), \fBbyteorder\fR(3C), \fBnetdir\fR(3NSL),
\fBnetconfig\fR(4), \fBnsswitch.conf\fR(4), \fBservices\fR(4),
\fBattributes\fR(5), \fBnetdb.h\fR(3HEAD)
.SH WARNINGS
.LP
The reentrant interfaces \fBgetservbyname_r()\fR, \fBgetservbyport_r()\fR, and
\fBgetservent_r()\fR are included in this release on an uncommitted basis only,
and are subject to change or removal in future minor releases.
.SH NOTES
.LP
The functions that return \fBstruct servent\fR return the least significant
16-bits of the \fIs_port\fR field in \fInetwork byte order\fR.
\fBgetservbyport()\fR and \fBgetservbyport_r()\fR also expect the input
parameter \fIport\fR in the \fInetwork byte order\fR. See \fBhtons\fR(3C)
for more details on converting between host and network byte orders.
.sp
.LP
To ensure that they all return consistent results, \fBgetservbyname()\fR,
\fBgetservbyname_r()\fR, and \fBnetdir_getbyname()\fR are implemented in terms
of the same internal library function. This function obtains the system-wide
source lookup policy based on the \fBinet\fR family entries in
\fBnetconfig\fR(4) and the \fBservices:\fR entry in \fBnsswitch.conf\fR(4).
Similarly, \fBgetservbyport()\fR, \fBgetservbyport_r()\fR, and
\fBnetdir_getbyaddr()\fR are implemented in terms of the same internal library
function. If the \fBinet\fR family entries in \fBnetconfig\fR(4) have a ``-''
in the last column for nametoaddr libraries, then the entry for \fBservices\fR
in \fBnsswitch.conf\fR will be used; otherwise the nametoaddr libraries in that
column will be used, and \fBnsswitch.conf\fR will not be consulted.
.sp
.LP
There is no analogue of \fBgetservent()\fR and \fBgetservent_r()\fR in the
netdir functions, so these enumeration functions go straight to the
\fBservices\fR entry in \fBnsswitch.conf\fR. Thus enumeration may return
results from a different source than that used by \fBgetservbyname()\fR,
\fBgetservbyname_r()\fR, \fBgetservbyport()\fR, and \fBgetservbyport_r()\fR.
.sp
.LP
When compiling multithreaded applications, see  \fBIntro\fR(3), \fINotes On
Multithread Applications\fR, for information about the use of the
\fB_REENTRANT\fR flag.
.sp
.LP
Use of the enumeration interfaces \fBgetservent()\fR and \fBgetservent_r()\fR
is discouraged; enumeration may not be supported for all database sources.  The
semantics of enumeration are discussed further in \fBnsswitch.conf\fR(4).