Adding upstream version 6.05.01.upstream/6.05.01

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

1 files changed, 170 insertions, 0 deletions

diff --git a/man3/ttyslot.3 b/man3/ttyslot.3
new file mode 100644
index 0000000..d50af49
--- /dev/null
+++ b/man3/ttyslot.3
@@ -0,0 +1,170 @@
+'\" t
+.\" Copyright (C) 2002 Andries Brouwer <aeb@cwi.nl>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" This replaces an earlier man page written by Walter Harms
+.\" <walter.harms@informatik.uni-oldenburg.de>.
+.\"
+.TH ttyslot 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+ttyslot \- find the slot of the current user's terminal in some file
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <unistd.h>" "       /* See NOTES */"
+.PP
+.B "int ttyslot(void);"
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR ttyslot ():
+.nf
+    Since glibc 2.24:
+        _DEFAULT_SOURCE
+    From glibc 2.20 to glibc 2.23:
+        _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)
+    glibc 2.19 and earlier:
+        _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)
+.fi
+.SH DESCRIPTION
+The legacy function
+.BR ttyslot ()
+returns the index of the current user's entry in some file.
+.PP
+Now "What file?" you ask.
+Well, let's first look at some history.
+.SS Ancient history
+There used to be a file
+.I /etc/ttys
+in UNIX\ V6, that was read by the
+.BR init (1)
+program to find out what to do with each terminal line.
+Each line consisted of three characters.
+The first character was either \[aq]0\[aq] or \[aq]1\[aq],
+where \[aq]0\[aq] meant "ignore".
+The second character denoted the terminal: \[aq]8\[aq] stood for "/dev/tty8".
+The third character was an argument to
+.BR getty (8)
+indicating the sequence of line speeds to try (\[aq]\-\[aq] was: start trying
+110 baud).
+Thus a typical line was "18\-".
+A hang on some line was solved by changing the \[aq]1\[aq] to a \[aq]0\[aq],
+signaling init, changing back again, and signaling init again.
+.PP
+In UNIX\ V7 the format was changed: here the second character
+was the argument to
+.BR getty (8)
+indicating the sequence of line speeds to try (\[aq]0\[aq] was: cycle through
+300-1200-150-110 baud; \[aq]4\[aq] was for the on-line console DECwriter)
+while the rest of the line contained the name of the tty.
+Thus a typical line was "14console".
+.PP
+Later systems have more elaborate syntax.
+System V-like systems have
+.I /etc/inittab
+instead.
+.SS Ancient history (2)
+On the other hand, there is the file
+.I /etc/utmp
+listing the people currently logged in.
+It is maintained by
+.BR login (1).
+It has a fixed size, and the appropriate index in the file was
+determined by
+.BR login (1)
+using the
+.BR ttyslot ()
+call to find the number of the line in
+.I /etc/ttys
+(counting from 1).
+.SS The semantics of ttyslot
+Thus, the function
+.BR ttyslot ()
+returns the index of the controlling terminal of the calling process
+in the file
+.IR /etc/ttys ,
+and that is (usually) the same as the index of the entry for the
+current user in the file
+.IR /etc/utmp .
+BSD still has the
+.I /etc/ttys
+file, but System V-like systems do not, and hence cannot refer to it.
+Thus, on such systems the documentation says that
+.BR ttyslot ()
+returns the current user's index in the user accounting data base.
+.SH RETURN VALUE
+If successful, this function returns the slot number.
+On error (e.g., if none of the file descriptors 0, 1, or 2 is
+associated with a terminal that occurs in this data base)
+it returns 0 on UNIX\ V6 and V7 and BSD-like systems,
+but \-1 on System V-like systems.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR ttyslot ()
+T}	Thread safety	MT-Unsafe
+.TE
+.sp 1
+.SH VERSIONS
+The utmp file is found in various places on various systems, such as
+.IR /etc/utmp ,
+.IR /var/adm/utmp ,
+.IR /var/run/utmp .
+.SH STANDARDS
+None.
+.SH HISTORY
+SUSv1; marked as LEGACY in SUSv2; removed in POSIX.1-2001.
+SUSv2 requires \-1 on error.
+.PP
+The glibc2 implementation of this function reads the file
+.BR _PATH_TTYS ,
+defined in
+.I <ttyent.h>
+as "/etc/ttys".
+It returns 0 on error.
+Since Linux systems do not usually have "/etc/ttys", it will
+always return 0.
+.PP
+On BSD-like systems and Linux, the declaration of
+.BR ttyslot ()
+is provided by
+.IR <unistd.h> .
+On System V-like systems, the declaration is provided by
+.IR <stdlib.h> .
+Since glibc 2.24,
+.I <stdlib.h>
+also provides the declaration with the following
+feature test macro definitions:
+.PP
+.in +4n
+.EX
+(_XOPEN_SOURCE >= 500 ||
+        (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED))
+    && ! (_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600)
+.EE
+.in
+.PP
+Minix also has
+.IR fttyslot ( fd ).
+.\" .SH HISTORY
+.\" .BR ttyslot ()
+.\" appeared in UNIX V7.
+.SH SEE ALSO
+.BR getttyent (3),
+.BR ttyname (3),
+.BR utmp (5)