1getprotobyname(3SOCKET)    Sockets Library Functions   getprotobyname(3SOCKET)
2
3
4

NAME

6       getprotobyname, getprotobyname_r, getprotobynumber, getprotobynumber_r,
7       getprotoent, getprotoent_r, setprotoent,  endprotoent  -  get  protocol
8       entry
9

SYNOPSIS

11       cc [ flag ... ] file ... -lsocket  -lnsl  [ library ... ]
12       #include <netdb.h>
13
14       struct protoent *getprotobyname(const char *name);
15
16
17       struct protoent *getprotobyname_r(const char *name,
18            struct protoent *result, char *buffer,
19            int buflen);
20
21
22       struct protoent *getprotobynumber(int proto);
23
24
25       struct protoent *getprotobynumber_r(int proto, struct protoent *result,
26            char *buffer, int buflen);
27
28
29       struct protoent *getprotoent(void);
30
31
32       struct protoent *getprotoent_r(struct protoent *result, char *buffer,
33            int buflen);
34
35
36       int setprotoent(int stayopen);
37
38
39       int endprotoent(void);
40
41

DESCRIPTION

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
50
51       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
58
59       getprotobyname_r(),   getprotobynumber_r(),  and  getprotoent_r()  each
60       return a protocol entry.
61
62
63       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
71
72       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
76
77       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
82
83       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
89
90       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
94
95       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
106
107       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
112
113       The internal representation of a protocol entry is a protoent structure
114       defined in <netdb.h> with the following members:
115
116         char  *p_name;
117         char  **p_aliases;
118         int   p_proto;
119
120

RETURN VALUES

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
127
128       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

ERRORS

133       The getprotobyname_r(), getprotobynumber_r(), and getprotoent_r() func‐
134       tions will fail if:
135
136       ERANGE    The length of the buffer supplied by the caller is not  large
137                 enough to store the result.
138
139

FILES

141       /etc/protocols
142
143
144       /etc/nsswitch.conf
145

ATTRIBUTES

147       See attributes(5) for descriptions of the following attributes:
148
149
150
151
152       ┌─────────────────────────────┬─────────────────────────────┐
153       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
154       ├─────────────────────────────┼─────────────────────────────┤
155       │MT-Level                     │See NOTES below.             │
156       └─────────────────────────────┴─────────────────────────────┘
157

SEE ALSO

159       Intro(3), nsswitch.conf(4), protocols(4), attributes(5), netdb.h(3HEAD)
160

NOTES

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
166
167       When compiling multithreaded applications, see  Intro(3), Notes On Mul‐
168       tithread Applications, for information about the use of the  _REENTRANT
169       flag.
170
171
172       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
177
178       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
183
184       The  setprotoent() and endprotoent() functions have process-wide scope,
185       and are therefore not safe in multi-threaded applications.
186
187
188       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

BUGS

194       Only the Internet protocols are currently understood.
195
196
197
198SunOS 5.11                        5 Apr 2004           getprotobyname(3SOCKET)
Impressum