.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
.\" References consulted:
.\" Linux libc source code
.\" Modified Mon Apr 22 01:50:54 1996 by Martin Schulze <joey@infodrom.north.de>
.\" 2001-07-25 added a clause about NULL proto (Martin Michlmayr or David N. Welton)
.\"
-.TH GETSERVENT 3 2001-07-25 "BSD" "Linux Programmer's Manual"
+.TH GETSERVENT 3 2017-09-15 "GNU" "Linux Programmer's Manual"
.SH NAME
getservent, getservbyname, getservbyport, setservent, endservent \-
get service entry
.SH SYNOPSIS
.nf
.B #include <netdb.h>
-.sp
+.PP
.B struct servent *getservent(void);
-.sp
+.PP
.BI "struct servent *getservbyname(const char *" name ", const char *" proto );
-.sp
+.PP
.BI "struct servent *getservbyport(int " port ", const char *" proto );
-.sp
+.PP
.BI "void setservent(int " stayopen );
-.sp
+.PP
.B void endservent(void);
.fi
.SH DESCRIPTION
The
.BR getservent ()
-function reads the next line from the file
-\fI/etc/services\fP and returns a structure \fIservent\fP containing
-the broken out fields from the line.
-The \fI/etc/services\fP file
-is opened if necessary.
+function reads the next entry from the services database (see
+.BR services (5))
+and returns a
+.I servent
+structure containing
+the broken-out fields from the entry.
+A connection is opened to the database if necessary.
.PP
The
.BR getservbyname ()
-function returns a \fIservent\fP structure
-for the line from \fI/etc/services\fP that matches the service
-\fIname\fP using protocol \fIproto\fP.
-If \fIproto\fP is NULL, any protocol will be matched.
+function returns a
+.I servent
+structure
+for the entry from the database
+that matches the service
+.I name
+using protocol
+.IR proto .
+If
+.I proto
+is NULL, any protocol will be matched.
+A connection is opened to the database if necessary.
.PP
The
.BR getservbyport ()
-function returns a \fIservent\fP structure
-for the line that matches the port \fIport\fP given in network byte order
-using protocol \fIproto\fP.
-If \fIproto\fP is NULL, any protocol will be matched.
+function returns a
+.I servent
+structure
+for the entry from the database
+that matches the port
+.I port
+(given in network byte order)
+using protocol
+.IR proto .
+If
+.I proto
+is NULL, any protocol will be matched.
+A connection is opened to the database if necessary.
.PP
The
.BR setservent ()
-function opens and rewinds the
-\fI/etc/services\fP file.
-If \fIstayopen\fP is true (1), then the
-file will not be closed between calls to
-.BR getservbyname ()
-and
-.BR getservbyport ().
+function opens a connection to the database,
+and sets the next entry to the first entry.
+If
+.I stayopen
+is nonzero,
+then the connection to the database
+will not be closed between calls to one of the
+.BR getserv* ()
+functions.
.PP
The
.BR endservent ()
-function closes \fI/etc/services\fP.
+function closes the connection to the database.
.PP
-The \fIservent\fP structure is defined in \fI<netdb.h>\fP as follows:
-.sp
-.RS
-.nf
+The
+.I servent
+structure is defined in
+.I <netdb.h>
+as follows:
+.PP
+.in +4n
+.EX
struct servent {
char *s_name; /* official service name */
char **s_aliases; /* alias list */
int s_port; /* port number */
char *s_proto; /* protocol to use */
}
-.fi
-.RE
+.EE
+.in
.PP
-The members of the \fIservent\fP structure are:
+The members of the
+.I servent
+structure are:
.TP
.I s_name
The official name of the service.
.TP
.I s_aliases
-A zero terminated list of alternative names for the service.
+A NULL-terminated list of alternative names for the service.
.TP
.I s_port
The port number for the service given in network byte order.
.TP
.I s_proto
The name of the protocol to use with this service.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
The
.BR getservent (),
.BR getservbyname ()
and
.BR getservbyport ()
-functions return the \fIservent\fP structure, or a NULL pointer if an
+functions return a pointer to a
+statically allocated
+.I servent
+structure, or NULL if an
error occurs or the end of the file is reached.
.SH FILES
.TP
.I /etc/services
services database file
-.SH "CONFORMING TO"
-4.3BSD, POSIX.1-2001.
-.SH "SEE ALSO"
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbw15 lb lbw25
+l l l.
+Interface Attribute Value
+T{
+.BR getservent ()
+T} Thread safety T{
+MT-Unsafe race:servent
+.br
+race:serventbuf locale
+T}
+T{
+.BR getservbyname ()
+T} Thread safety T{
+MT-Unsafe race:servbyname
+.br
+locale
+T}
+T{
+.BR getservbyport ()
+T} Thread safety T{
+MT-Unsafe race:servbyport
+.br
+locale
+T}
+T{
+.BR setservent (),
+.br
+.BR endservent ()
+T} Thread safety T{
+MT-Unsafe race:servent
+.br
+locale
+T}
+.TE
+.sp 1
+In the above table,
+.I servent
+in
+.I race:servent
+signifies that if any of the functions
+.BR setservent (),
+.BR getservent (),
+or
+.BR endservent ()
+are used in parallel in different threads of a program,
+then data races could occur.
+.SH CONFORMING TO
+POSIX.1-2001, POSIX.1-2008, 4.3BSD.
+.SH SEE ALSO
.BR getnetent (3),
.BR getprotoent (3),
+.BR getservent_r (3),
.BR services (5)
projects / thirdparty / man-pages.git / blobdiff