1 files changed, 114 insertions, 0 deletions
diff --git a/man3/login.3 b/man3/login.3
new file mode 100644
index 000000000..d9c1e9b6d
--- /dev/null
+++ b/man3/login.3
@@ -0,0 +1,114 @@
+.\" This is free documentation; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License as
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, write to the Free
+.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
+.\" USA.
+.\"
+.\" Derived from text written by Martin Schulze (or taken from glibc.info)
+.\" and text written by Paul Thompson - both copyright 2002.
+.\"
+.TH LOGIN 3 2004-05-06 "GNU/Linux" "Linux System Administration"
+.SH NAME
+login, logout \- write utmp and wtmp entries
+.SH SYNOPSIS
+.B #include <utmp.h>
+.sp
+.BI "void login(const struct utmp *" ut );
+.br
+.BI "int logout(const char *" ut_line );
+.SH DESCRIPTION
+The utmp file records who is currently using the system.
+The wtmp file records all logins and logouts. See
+.BR utmp (5).
+.LP
+The function
+.BR login ()
+takes the supplied struct utmp
+.IR ut ,
+and writes it to both utmp and wtmp file.
+.LP
+The function
+.BR logout ()
+clears the entry in the utmp file again.
+.SH "GNU DETAILS"
+More precisely,
+.BR login ()
+takes the argument
+.I ut
+struct, fills the field
+.I ut->ut_type
+(if there is such a field) with the value
+.BR USER_PROCESS ,
+and fills the field
+.I ut->ut_pid
+(if there is such a field) with the process ID of the calling process.
+Then it tries to fill the field
+.IR ut->ut_line .
+It takes the first of stdin, stdout, stderr that is a tty, and
+stores the corresponding pathname minus a possible leading /dev/
+into this field, and then writes the struct to the utmp file.
+On the other hand, if no tty name was found, this field is filled with "???"
+and the struct is not written to the utmp file.
+After this, the struct is written to the wtmp file.
+.LP
+The
+.BR logout ()
+function searches the utmp file for an entry matching the
+.I ut_line
+argument. If a record is found, it is updated by zeroing out the
+.I ut_name
+and
+.I ut_host
+fields, updating the
+.I ut_tv
+timestamp field and setting
+.I ut_type
+(if there is such a field) to
+.BR DEAD_PROCESS .
+.SH "RETURN VALUES"
+The
+.BR logout ()
+function returns 1 if the entry was successfully written to the
+database, or 0 if an error occurred.
+.SH NOTE
+These functions are included in libutil, hence you'll need to add
+.B \-lutil
+to your compiler commandline.
+
+Note that the
+member
+.B ut_user
+of struct utmp is called
+.B ut_name
+in BSD.  Therefore,
+.B ut_name
+is defined as an alias for
+.B ut_user
+in
+.IR utmp.h .
+.SH FILES
+.TP
+.I /var/run/utmp
+user accounting database, configured through _PATH_UTMP in
+.I <paths.h>
+.TP
+.I /var/log/wtmp
+user accounting log file, configured through _PATH_WTMP in
+.I <paths.h>
+.SH "SEE ALSO"
+.BR getutent (3),
+.BR utmp (5)