original/man3/login.3

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