man3/login.3

   1 .\" Derived from text written by Martin Schulze (or taken from glibc.info)
   2 .\" and text written by Paul Thompson - both copyright 2002.
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, see
  22 .\" <http://www.gnu.org/licenses/>.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH LOGIN 3 2004-05-06 "GNU" "Linux Programmer's Manual"
  26 .SH NAME
  27 login, logout \- write utmp and wtmp entries
  28 .SH SYNOPSIS
  29 .B #include <utmp.h>
  30 .sp
  31 .BI "void login(const struct utmp *" ut );
  32 .sp
  33 .BI "int logout(const char *" ut_line );
  34 .sp
  35 Link with \fI\-lutil\fP.
  36 .SH DESCRIPTION
  37 The utmp file records who is currently using the system.
  38 The wtmp file records all logins and logouts.
  39 See
  40 .BR utmp (5).
  41 .LP
  42 The function
  43 .BR login ()
  44 takes the supplied \fIstruct utmp\fP,
  45 .IR ut ,
  46 and writes it to both the utmp and the wtmp file.
  47 .LP
  48 The function
  49 .BR logout ()
  50 clears the entry in the utmp file again.
  51 .SS GNU details
  52 More precisely,
  53 .BR login ()
  54 takes the argument
  55 .I ut
  56 struct, fills the field
  57 .I ut\->ut_type
  58 (if there is such a field) with the value
  59 .BR USER_PROCESS ,
  60 and fills the field
  61 .I ut\->ut_pid
  62 (if there is such a field) with the process ID of the calling process.
  63 Then it tries to fill the field
  64 .IR ut\->ut_line .
  65 It takes the first of \fIstdin\fP, \fIstdout\fP, \fIstderr\fP
  66 that is a terminal, and
  67 stores the corresponding pathname minus a possible leading \fI/dev/\fP
  68 into this field, and then writes the struct to the utmp file.
  69 On the other hand, if no terminal name was found, this field is filled with "???"
  70 and the struct is not written to the utmp file.
  71 After this, the struct is written to the wtmp file.
  72 .LP
  73 The
  74 .BR logout ()
  75 function searches the utmp file for an entry matching the
  76 .I ut_line
  77 argument.
  78 If a record is found, it is updated by zeroing out the
  79 .I ut_name
  80 and
  81 .I ut_host
  82 fields, updating the
  83 .I ut_tv
  84 timestamp field and setting
  85 .I ut_type
  86 (if there is such a field) to
  87 .BR DEAD_PROCESS .
  88 .SH RETURN VALUE
  89 The
  90 .BR logout ()
  91 function returns 1 if the entry was successfully written to the
  92 database, or 0 if an error occurred.
  93 .SH FILES
  94 .TP
  95 .I /var/run/utmp
  96 user accounting database, configured through
  97 .B _PATH_UTMP
  98 in
  99 .I <paths.h>
 100 .TP
 101 .I /var/log/wtmp
 102 user accounting log file, configured through
 103 .B _PATH_WTMP
 104 in
 105 .I <paths.h>
 106 .SH CONFORMING TO
 107 Not in POSIX.1-2001.
 108 Present on the BSDs.
 109 .SH NOTES
 110 Note that the
 111 member
 112 .I ut_user
 113 of
 114 .I struct utmp
 115 is called
 116 .I ut_name
 117 in BSD.
 118 Therefore,
 119 .I ut_name
 120 is defined as an alias for
 121 .I ut_user
 122 in
 123 .IR <utmp.h> .
 124 .SH SEE ALSO
 125 .BR getutent (3),
 126 .BR utmp (5)