Sockets Library Functions getprotobyname(3SOCKET)
NAME
getprotobyname, getprotobynamer, getprotobynumber,
getprotobynumberr, getprotoent, getprotoentr, setprotoent,
endprotoent - get protocol entry
SYNOPSIS
cc [ flag ... ] file ... -lsocket -lnsl [ library ... ]
#include
struct protoent *getprotobyname(const char *name);
struct protoent *getprotobynamer(const char *name,
struct protoent *result, char *buffer,
int buflen);
struct protoent *getprotobynumber(int proto);
struct protoent *getprotobynumberr(int proto, struct protoent *result,
char *buffer, int buflen);
struct protoent *getprotoent(void);
struct protoent *getprotoentr(struct protoent *result, char *buffer,
int buflen);
int setprotoent(int stayopen);
int endprotoent(void);
DESCRIPTION
These functions return a protocol entry. Two types of inter-
faces are supported: reentrant (getprotobynamer(),
getprotobynumberr(), and getprotoentr()) and non-reentrant
(getprotobyname(), getprotobynumber(), and getprotoent()).
The reentrant functions can be used in single-threaded
applications and are safe for multithreaded applications,
making them the preferred interfaces.
The reentrant routines require additional parameters which
are used to return results data. result is a pointer to a
struct protoent structure and will be where the returned
results will be stored. buffer is used as storage space for
elements of the returned results. buflen is the size of
SunOS 5.11 Last change: 5 Apr 2004 1
Sockets Library Functions getprotobyname(3SOCKET)
buffer and should be large enough to contain all returned
data. buflen must be at least 1024 bytes.
getprotobynamer(), getprotobynumberr(), and
getprotoentr() each return a protocol entry.
The entry may come from one of the following sources: the
protocols file (see protocols(4)), the NIS maps
``protocols.byname'' and ``protocols.bynumber'', and the
NIS] table ``protocols''. The sources and their lookup order
are specified in the /etc/nsswitch.conf file (see
nsswitch.conf(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.
The getprotobynamer() and getprotobynumberr() 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.
getprotobyname() and getprotobynumber() have the same func-
tionality as getprotobynamer() and getprotobynumberr()
except that a static buffer is used to store returned
results. These functions are Unsafe in a multithreaded
application.
getprotoentr() enumerates protocol entries: successive
calls to getprotoentr() will return either successive pro-
tocol entries or NUL. Enumeration might not be supported by
some sources. If multiple threads call getprotoentr(), each
will retrieve a subset of the protocol database.
getprotent() has the same functionality as getprotentr()
except that a static buffer is used to store returned
results. This routine is unsafe in a multithreaded applica-
tion.
setprotoent() "rewinds" to the beginning of the enumeration
of protocol entries. If the stayopen flag is non-zero,
resources such as open file descriptors are not deallocated
after each call to getprotobynumberr() and
getprotobynamer(). Calls to getprotobynamer() , The get-
protobyname(), getprotobynumberr(), and getprotobynumber()
functions might leave the enumeration in an indeterminate
state, so setprotoent() should be called before the first
SunOS 5.11 Last change: 5 Apr 2004 2
Sockets Library Functions getprotobyname(3SOCKET)
call to getprotoentr() or getprotoent(). The setprotoent()
function has process-wide scope, and ``rewinds'' the proto-
col entries for all threads calling getprotoentr() as well
as main-thread calls to getprotoent().
The endprotoent() 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 endprotoent().
The internal representation of a protocol entry is a pro-
toent structure defined in with the following
members:
char *pname;
char **paliases;
int pproto;
RETURN VALUES
The getprotobynamer(), getprotobyname(),
getprotobynumberr(), and getprotobynumber() functions
return a pointer to a struct protoent if they successfully
locate the requested entry; otherwise they return NUL.
The getprotoentr() and getprotoent() functions return a
pointer to a struct protoent if they successfully enumerate
an entry; otherwise they return NUL, indicating the end of
the enumeration.
ERORS
The getprotobynamer(), getprotobynumberr(), and
getprotoentr() functions will fail if:
ERANGE The length of the buffer supplied by the caller is
not large enough to store the result.
FILES
/etc/protocols
/etc/nsswitch.conf
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 5 Apr 2004 3
Sockets Library Functions getprotobyname(3SOCKET)
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level See NOTES below.
SEE ALSO
Intro(3), nsswitch.conf(4), protocols(4), attributes(5),
netdb.h(3HEAD)
NOTES
Although getprotobynamer(), getprotobynumberr(), and
getprotoentr() are not mentioned by POSIX 1003.1:2001, they
were added to complete the functionality provided by similar
thread-safe functions.
When compiling multithreaded applications, see Intro(3),
Notes On Multithread Applications, for information about the
use of the RENTRANT flag.
The getprotobynamer(), getprotobynumberr(), and
getprotoentr() 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.
The getprotobyname(), getprotobyaddr(), and getprotoent()
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.
The setprotoent() and endprotoent() functions have process-
wide scope, and are therefore not safe in multi-threaded
applications.
Use of getprotoentr() and getprotoent() is discouraged;
enumeration is well-defined for the protocols file and is
supported (albeit inefficiently) for NIS and NIS], but in
general may not be well-defined. The semantics of enumera-
tion are discussed in nsswitch.conf(4).
BUGS
Only the Internet protocols are currently understood.
SunOS 5.11 Last change: 5 Apr 2004 4
|
