diff options
Diffstat (limited to 'usr/src/man/man3socket/getservbyname.3socket')
| -rw-r--r-- | usr/src/man/man3socket/getservbyname.3socket | 354 |
1 files changed, 354 insertions, 0 deletions
diff --git a/usr/src/man/man3socket/getservbyname.3socket b/usr/src/man/man3socket/getservbyname.3socket new file mode 100644 index 0000000000..606ca35ff2 --- /dev/null +++ b/usr/src/man/man3socket/getservbyname.3socket @@ -0,0 +1,354 @@ +'\" 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 "31 Jan 2007" "SunOS 5.11" "Sockets Library Functions" +.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 +.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 +.mk +.na +\fB\fBs_name\fR\fR +.ad +.RS 13n +.rt +The official name of the service. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBs_aliases\fR\fR +.ad +.RS 13n +.rt +A zero terminated list of alternate names for the service. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBs_port\fR\fR +.ad +.RS 13n +.rt +The port number at which the service resides. Port numbers are +returned in network byte order. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBs_proto\fR\fR +.ad +.RS 13n +.rt +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 +.mk +.na +\fB\fB/etc/services\fR\fR +.ad +.RS 22n +.rt +Internet network services +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/netconfig\fR\fR +.ad +.RS 22n +.rt +network configuration file +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/nsswitch.conf\fR\fR +.ad +.RS 22n +.rt +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 +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelT{ +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). |