'\" 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 \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 .sp .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(3SOCKET) 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" .sp .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 .sp .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 .sp .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 .sp .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 .sp .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 .sp .LP \fBIntro\fR(2), \fBIntro\fR(3), \fBbyteorder\fR(3SOCKET), \fBnetdir\fR(3NSL), \fBnetconfig\fR(4), \fBnsswitch.conf\fR(4), \fBservices\fR(4), \fBattributes\fR(5), \fBnetdb.h\fR(3HEAD) .SH WARNINGS .sp .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 .sp .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(3SOCKET) 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).