'\" 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 "Apr 5, 2004"
.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
.na
\fB\fBERANGE\fR\fR
.ad
.RS 10n
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
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	See \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.