diff options
Diffstat (limited to 'usr/src/man/man3socket/getprotobyname.3socket')
| -rw-r--r-- | usr/src/man/man3socket/getprotobyname.3socket | 235 |
1 files changed, 235 insertions, 0 deletions
diff --git a/usr/src/man/man3socket/getprotobyname.3socket b/usr/src/man/man3socket/getprotobyname.3socket new file mode 100644 index 0000000000..bfaac47db5 --- /dev/null +++ b/usr/src/man/man3socket/getprotobyname.3socket @@ -0,0 +1,235 @@ +'\" 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) 2000, Sun Microsystems, Inc. All Rights Reserved. +.TH getprotobyname 3SOCKET "5 Apr 2004" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +getprotobyname, getprotobyname_r, getprotobynumber, getprotobynumber_r, +getprotoent, getprotoent_r, setprotoent, endprotoent \- get protocol entry +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] +#include <netdb.h> + +\fBstruct protoent *\fR\fBgetprotobyname\fR(\fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBstruct protoent *\fR\fBgetprotobyname_r\fR(\fBconst char *\fR\fIname\fR, + \fBstruct protoent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, + \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBstruct protoent *\fR\fBgetprotobynumber\fR(\fBint\fR \fIproto\fR); +.fi + +.LP +.nf +\fBstruct protoent *\fR\fBgetprotobynumber_r\fR(\fBint\fR \fIproto\fR, \fBstruct protoent *\fR\fIresult\fR, + \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBstruct protoent *\fR\fBgetprotoent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBstruct protoent *\fR\fBgetprotoent_r\fR(\fBstruct protoent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, + \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBint\fR \fBsetprotoent\fR(\fBint\fR \fIstayopen\fR); +.fi + +.LP +.nf +\fBint\fR \fBendprotoent\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions return a protocol entry. Two types of interfaces are supported: +reentrant (\fBgetprotobyname_r()\fR, \fBgetprotobynumber_r()\fR, and +\fBgetprotoent_r()\fR) and non-reentrant (\fBgetprotobyname()\fR, +\fBgetprotobynumber()\fR, and \fBgetprotoent()\fR). The reentrant functions can +be used in single-threaded applications and are safe for multithreaded +applications, making them the preferred interfaces. +.sp +.LP +The reentrant routines require additional parameters which are used to return +results data. \fIresult\fR is a pointer to a \fBstruct protoent\fR structure +and will be where the returned results will be stored. \fIbuffer\fR is used as +storage space for elements of the returned results. \fIbuflen\fR is the size of +\fIbuffer\fR and should be large enough to contain all returned data. +\fIbuflen\fR must be at least 1024 bytes. +.sp +.LP +\fBgetprotobyname_r()\fR, \fBgetprotobynumber_r()\fR, and \fBgetprotoent_r()\fR +each return a protocol entry. +.sp +.LP +The entry may come from one of the following sources: the protocols file (see +\fBprotocols\fR(4)), the \fBNIS\fR maps ``protocols.byname'' and +``protocols.bynumber'', and the \fBNIS+\fR table ``protocols''. The sources and +their lookup order are specified in the \fB/etc/nsswitch.conf\fR file (see +\fBnsswitch.conf\fR(4) for details). Some name services such as NIS will return +only one name for a host, whereas others such as NIS+ or DNS will return all +aliases. +.sp +.LP +The \fBgetprotobyname_r()\fR and \fBgetprotobynumber_r()\fR functions +sequentially search from the beginning of the file until a matching protocol +name or protocol number is found, or until an EOF is encountered. +.sp +.LP +\fBgetprotobyname()\fR and \fBgetprotobynumber()\fR have the same functionality +as \fBgetprotobyname_r()\fR and \fBgetprotobynumber_r()\fR except that a static +buffer is used to store returned results. These functions are Unsafe in a +multithreaded application. +.sp +.LP +\fBgetprotoent_r()\fR enumerates protocol entries: successive calls to +\fBgetprotoent_r()\fR will return either successive protocol entries or +\fINULL\fR. Enumeration might not be supported by some sources. If multiple +threads call \fBgetprotoent_r()\fR, each will retrieve a subset of the protocol +database. +.sp +.LP +\fBgetprotent()\fR has the same functionality as \fBgetprotent_r()\fR except +that a static buffer is used to store returned results. This routine is unsafe +in a multithreaded application. +.sp +.LP +\fBsetprotoent()\fR "rewinds" to the beginning of the enumeration of protocol +entries. If the \fIstayopen\fR flag is non-zero, resources such as open file +descriptors are not deallocated after each call to \fBgetprotobynumber_r()\fR +and \fBgetprotobyname_r()\fR. Calls to \fBgetprotobyname_r()\fR \fB,\fR The +\fBgetprotobyname()\fR, \fBgetprotobynumber_r()\fR, and +\fBgetprotobynumber()\fR functions might leave the enumeration in an +indeterminate state, so \fBsetprotoent()\fR should be called before the first +call to \fBgetprotoent_r()\fR or \fBgetprotoent()\fR. The \fBsetprotoent()\fR +function has process-wide scope, and ``rewinds'' the protocol entries for all +threads calling \fBgetprotoent_r()\fR as well as main-thread calls to +\fBgetprotoent()\fR. +.sp +.LP +The \fBendprotoent()\fR function can be called to indicate that protocol +processing is complete; the system may then close any open protocols file, +deallocate storage, and so forth. It is legitimate, but possibly less +efficient, to call more protocol functions after \fBendprotoent()\fR. +.sp +.LP +The internal representation of a protocol entry is a \fBprotoent\fR structure +defined in <\fBnetdb.h\fR> with the following members: +.sp +.in +2 +.nf +char *p_name; +char **p_aliases; +int p_proto; +.fi +.in -2 + +.SH RETURN VALUES +.sp +.LP +The \fBgetprotobyname_r()\fR, \fBgetprotobyname()\fR, +\fBgetprotobynumber_r()\fR, and \fBgetprotobynumber()\fR functions return a +pointer to a \fBstruct protoent\fR if they successfully locate the requested +entry; otherwise they return \fBNULL.\fR +.sp +.LP +The \fBgetprotoent_r()\fR and \fBgetprotoent()\fR functions return a pointer to +a \fBstruct protoent\fR if they successfully enumerate an entry; otherwise they +return \fINULL\fR, indicating the end of the enumeration. +.SH ERRORS +.sp +.LP +The \fBgetprotobyname_r()\fR, \fBgetprotobynumber_r()\fR, and +\fBgetprotoent_r()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The length of the buffer supplied by the caller is not large enough to store +the result. +.RE + +.SH FILES +.sp +.LP +\fB/etc/protocols\fR +.sp +.LP +\fB/etc/nsswitch.conf\fR +.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-LevelSee \fBNOTES\fR below. +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(3), \fBnsswitch.conf\fR(4), \fBprotocols\fR(4), +\fBattributes\fR(5), \fBnetdb.h\fR(3HEAD) +.SH NOTES +.sp +.LP +Although \fBgetprotobyname_r()\fR, \fBgetprotobynumber_r()\fR, and +\fBgetprotoent_r()\fR are not mentioned by POSIX 1003.1:2001, they were added +to complete the functionality provided by similar thread-safe functions. +.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 +The \fBgetprotobyname_r()\fR, \fBgetprotobynumber_r()\fR, and +\fBgetprotoent_r()\fR functions are reentrant and multithread safe. The +reentrant interfaces can be used in single-threaded as well as multithreaded +applications and are therefore the preferred interfaces. +.sp +.LP +The \fBgetprotobyname()\fR, \fBgetprotobyaddr()\fR, and \fBgetprotoent()\fR +functions use static storage, so returned data must be copied if it is to be +saved. Because of their use of static storage for returned data, these +functions are not safe for multithreaded applications. +.sp +.LP +The \fBsetprotoent()\fR and \fBendprotoent()\fR functions have process-wide +scope, and are therefore not safe in multi-threaded applications. +.sp +.LP +Use of \fBgetprotoent_r()\fR and \fBgetprotoent()\fR is discouraged; +enumeration is well-defined for the protocols file and is supported (albeit +inefficiently) for \fBNIS\fR and \fBNIS+,\fR but in general may not be +well-defined. The semantics of enumeration are discussed in +\fBnsswitch.conf\fR(4). +.SH BUGS +.sp +.LP +Only the Internet protocols are currently understood. |