Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 209 insertions, 0 deletions

diff --git a/man/man3/getservent.3 b/man/man3/getservent.3
new file mode 100644
index 0000000..b3c4b26
--- /dev/null
+++ b/man/man3/getservent.3
@@ -0,0 +1,209 @@
+'\" t
+.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" References consulted:
+.\"     Linux libc source code
+.\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
+.\"     386BSD man pages
+.\" Modified Sat Jul 24 19:19:11 1993 by Rik Faith (faith@cs.unc.edu)
+.\" Modified Wed Oct 18 20:23:54 1995 by Martin Schulze <joey@infodrom.north.de>
+.\" 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 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+getservent, getservbyname, getservbyport, setservent, endservent \-
+get service entry
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <netdb.h>
+.P
+.B struct servent *getservent(void);
+.P
+.BI "struct servent *getservbyname(const char *" name ", const char *" proto );
+.BI "struct servent *getservbyport(int " port ", const char *" proto );
+.P
+.BI "void setservent(int " stayopen );
+.B void endservent(void);
+.fi
+.SH DESCRIPTION
+The
+.BR getservent ()
+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.
+.P
+The
+.BR getservbyname ()
+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.
+.P
+The
+.BR getservbyport ()
+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.
+.P
+The
+.BR setservent ()
+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.
+.P
+The
+.BR endservent ()
+function closes the connection to the database.
+.P
+The
+.I servent
+structure is defined in
+.I <netdb.h>
+as follows:
+.P
+.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 */
+}
+.EE
+.in
+.P
+The members of the
+.I servent
+structure are:
+.TP
+.I s_name
+The official name of the service.
+.TP
+.I s_aliases
+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
+The
+.BR getservent (),
+.BR getservbyname (),
+and
+.BR getservbyport ()
+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 ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lbx
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR getservent ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Unsafe race:servent
+race:serventbuf locale
+T}
+T{
+.na
+.nh
+.BR getservbyname ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Unsafe race:servbyname
+locale
+T}
+T{
+.na
+.nh
+.BR getservbyport ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Unsafe race:servbyport
+locale
+T}
+T{
+.na
+.nh
+.BR setservent (),
+.BR endservent ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Unsafe race:servent
+locale
+T}
+.TE
+.P
+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 STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, 4.3BSD.
+.SH SEE ALSO
+.BR getnetent (3),
+.BR getprotoent (3),
+.BR getservent_r (3),
+.BR services (5)