1getprotobyname(3SOCKET) Sockets Library Functions getprotobyname(3SOCKET)
2
6 getprotobyname, getprotobyname_r, getprotobynumber, getprotobynumber_r,
7 getprotoent, getprotoent_r, setprotoent, endprotoent - get protocol
8 entry
9
11 cc [ flag ... ] file ... -lsocket -lnsl [ library ... ]
12 #include <netdb.h>
13 struct protoent *getprotobyname(const char *name);
15 struct protoent *getprotobyname_r(const char *name,
18 struct protoent *result, char *buffer,
19 int buflen);
20 struct protoent *getprotobynumber(int proto);
23 struct protoent *getprotobynumber_r(int proto, struct protoent *result,
26 char *buffer, int buflen);
27 struct protoent *getprotoent(void);
30 struct protoent *getprotoent_r(struct protoent *result, char *buffer,
33 int buflen);
34 int setprotoent(int stayopen);
37 int endprotoent(void);
40
43 These functions return a protocol entry. Two types of interfaces are
44 supported: reentrant (getprotobyname_r(), getprotobynumber_r(), and
45 getprotoent_r()) and non-reentrant (getprotobyname(), getprotobynum‐
46 ber(), and getprotoent()). The reentrant functions can be used in sin‐
47 gle-threaded applications and are safe for multithreaded applications,
48 making them the preferred interfaces.
49 The reentrant routines require additional parameters which are used to
52 return results data. result is a pointer to a struct protoent structure
53 and will be where the returned results will be stored. buffer is used
54 as storage space for elements of the returned results. buflen is the
55 size of buffer and should be large enough to contain all returned data.
56 buflen must be at least 1024 bytes.
57 getprotobyname_r(), getprotobynumber_r(), and getprotoent_r() each
60 return a protocol entry.
61 The entry may come from one of the following sources: the protocols
64 file (see protocols(4)), the NIS maps ``protocols.byname'' and ``proto‐
65 cols.bynumber'', and the NIS+ table ``protocols''. The sources and
66 their lookup order are specified in the /etc/nsswitch.conf file (see
67 nsswitch.conf(4) for details). Some name services such as NIS will
68 return only one name for a host, whereas others such as NIS+ or DNS
69 will return all aliases.
70 The getprotobyname_r() and getprotobynumber_r() functions sequentially
73 search from the beginning of the file until a matching protocol name or
74 protocol number is found, or until an EOF is encountered.
75 getprotobyname() and getprotobynumber() have the same functionality as
78 getprotobyname_r() and getprotobynumber_r() except that a static buffer
79 is used to store returned results. These functions are Unsafe in a
80 multithreaded application.
81 getprotoent_r() enumerates protocol entries: successive calls to get‐
84 protoent_r() will return either successive protocol entries or NULL.
85 Enumeration might not be supported by some sources. If multiple threads
86 call getprotoent_r(), each will retrieve a subset of the protocol data‐
87 base.
88 getprotent() has the same functionality as getprotent_r() except that a
91 static buffer is used to store returned results. This routine is
92 unsafe in a multithreaded application.
93 setprotoent() "rewinds" to the beginning of the enumeration of protocol
96 entries. If the stayopen flag is non-zero, resources such as open file
97 descriptors are not deallocated after each call to getprotobynumber_r()
98 and getprotobyname_r(). Calls to getprotobyname_r() , The getprotoby‐
99 name(), getprotobynumber_r(), and getprotobynumber() functions might
100 leave the enumeration in an indeterminate state, so setprotoent()
101 should be called before the first call to getprotoent_r() or getpro‐
102 toent(). The setprotoent() function has process-wide scope, and
103 ``rewinds'' the protocol entries for all threads calling getpro‐
104 toent_r() as well as main-thread calls to getprotoent().
105 The endprotoent() function can be called to indicate that protocol pro‐
108 cessing is complete; the system may then close any open protocols file,
109 deallocate storage, and so forth. It is legitimate, but possibly less
110 efficient, to call more protocol functions after endprotoent().
111 The internal representation of a protocol entry is a protoent structure
114 defined in <netdb.h> with the following members:
115 char *p_name;
117 char **p_aliases;
118 int p_proto;
119
122 The getprotobyname_r(), getprotobyname(), getprotobynumber_r(), and
123 getprotobynumber() functions return a pointer to a struct protoent if
124 they successfully locate the requested entry; otherwise they return
125 NULL.
126 The getprotoent_r() and getprotoent() functions return a pointer to a
129 struct protoent if they successfully enumerate an entry; otherwise they
130 return NULL, indicating the end of the enumeration.
131
133 The getprotobyname_r(), getprotobynumber_r(), and getprotoent_r() func‐
134 tions will fail if:
135 ERANGE The length of the buffer supplied by the caller is not large
137 enough to store the result.
138
141 /etc/protocols
142 /etc/nsswitch.conf
145
147 See attributes(5) for descriptions of the following attributes:
148 ┌─────────────────────────────┬─────────────────────────────┐
153 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
154 ├─────────────────────────────┼─────────────────────────────┤
155 │MT-Level │See NOTES below. │
156 └─────────────────────────────┴─────────────────────────────┘
157
159 Intro(3), nsswitch.conf(4), protocols(4), attributes(5), netdb.h(3HEAD)
160
162 Although getprotobyname_r(), getprotobynumber_r(), and getprotoent_r()
163 are not mentioned by POSIX 1003.1:2001, they were added to complete the
164 functionality provided by similar thread-safe functions.
165 When compiling multithreaded applications, see Intro(3), Notes On Mul‐
168 tithread Applications, for information about the use of the _REENTRANT
169 flag.
170 The getprotobyname_r(), getprotobynumber_r(), and getprotoent_r() func‐
173 tions are reentrant and multithread safe. The reentrant interfaces can
174 be used in single-threaded as well as multithreaded applications and
175 are therefore the preferred interfaces.
176 The getprotobyname(), getprotobyaddr(), and getprotoent() functions use
179 static storage, so returned data must be copied if it is to be saved.
180 Because of their use of static storage for returned data, these func‐
181 tions are not safe for multithreaded applications.
182 The setprotoent() and endprotoent() functions have process-wide scope,
185 and are therefore not safe in multi-threaded applications.
186 Use of getprotoent_r() and getprotoent() is discouraged; enumeration is
189 well-defined for the protocols file and is supported (albeit ineffi‐
190 ciently) for NIS and NIS+, but in general may not be well-defined. The
191 semantics of enumeration are discussed in nsswitch.conf(4).
192
194 Only the Internet protocols are currently understood.
195SunOS 5.11 5 Apr 2004 getprotobyname(3SOCKET)