Return to endutxent.3 CVS log

Up to [cvs.NetBSD.org] / src / lib / libc / gen

Annotation of src/lib/libc/gen/endutxent.3, Revision 1.4

1.4     ! atatat      1: .\"    $NetBSD: endutxent.3,v 1.3 2003/06/27 14:23:24 wiz Exp $
1.1       wiz         2: .\"
                      3: .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
                      4: .\" All rights reserved.
                      5: .\"
                      6: .\" This code is derived from software contributed to The NetBSD Foundation
                      7: .\" by Thomas Klausner.
                      8: .\"
                      9: .\" Redistribution and use in source and binary forms, with or without
                     10: .\" modification, are permitted provided that the following conditions
                     11: .\" are met:
                     12: .\" 1. Redistributions of source code must retain the above copyright
                     13: .\"    notice, this list of conditions and the following disclaimer.
                     14: .\" 2. Redistributions in binary form must reproduce the above copyright
                     15: .\"    notice, this list of conditions and the following disclaimer in the
                     16: .\"    documentation and/or other materials provided with the distribution.
                     17: .\" 3. All advertising materials mentioning features or use of this software
                     18: .\"    must display the following acknowledgement:
                     19: .\"        This product includes software developed by the NetBSD
                     20: .\"        Foundation, Inc. and its contributors.
                     21: .\" 4. Neither the name of The NetBSD Foundation nor the names of its
                     22: .\"    contributors may be used to endorse or promote products derived
                     23: .\"    from this software without specific prior written permission.
                     24: .\"
                     25: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
                     26: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
                     27: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
                     28: .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
                     29: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
                     30: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
                     31: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
                     32: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
                     33: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
                     34: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
                     35: .\" POSSIBILITY OF SUCH DAMAGE.
                     36: .\"
                     37: .Dd September 26, 2002
                     38: .Dt ENDUTXENT 3
                     39: .Os
                     40: .Sh NAME
1.4     ! atatat     41: .Nm endutxent ,
1.1       wiz        42: .Nm getutxent ,
                     43: .Nm getutxid ,
                     44: .Nm getutxline ,
                     45: .Nm pututxline ,
                     46: .Nm setutxent
                     47: .Nd user accounting database functions
                     48: .Sh LIBRARY
                     49: .Lb libc
                     50: .Sh SYNOPSIS
1.2       wiz        51: .In utmpx.h
1.1       wiz        52: .Ft void
                     53: .Fn endutxent void
                     54: .Ft struct utmpx *
                     55: .Fn getutxent void
                     56: .Ft struct utmpx *
                     57: .Fn getutxid "const struct utmpx *"
                     58: .Ft struct utmpx *
                     59: .Fn getutxline "const struct utmpx *"
                     60: .Ft struct utmpx *
                     61: .Fn pututxline "const struct utmpx *"
                     62: .Ft void
                     63: .Fn setutxent void
                     64: .Sh DESCRIPTION
                     65: These functions provide access to the
                     66: .Xr utmpx 5
                     67: user accounting database.
                     68: .Pp
                     69: .Fn getutxent
                     70: reads the next entry from the database;
                     71: if the database was not yet open, it also opens it.
                     72: .Fn setutxent
                     73: resets the database, so that the next
                     74: .Fn getutxent
                     75: call will get the first entry.
                     76: .Fn endutxent
                     77: closes the database.
                     78: .Pp
                     79: .Fn getutxid
                     80: returns the next entry of the type specified in its argument's
                     81: .Va ut_type
                     82: field, or
                     83: .Dv NULL
                     84: if none is found.
                     85: .Fn getutxline
                     86: returns the next
                     87: .Dv LOGIN_PROCESS
                     88: or
                     89: .Dv USER_PROCESS
                     90: entry which has the same name as specified in the
                     91: .Va ut_line
                     92: field, or
                     93: .Dv NULL
                     94: if no match is found.
                     95: .Pp
                     96: .Fn pututxline
                     97: adds the argument
                     98: .Xr utmpx 5
                     99: entry line to the accounting database, replacing a previous entry for
                    100: the same user if it exists.
                    101: .Ss The utmpx structure
                    102: The
                    103: .Nm utmpx
                    104: structure has the following definition:
                    105: .Pp
                    106: .Bd -literal
                    107: struct utmpx {
                    108:         char ut_name[_UTX_USERSIZE];    /* login name */
                    109:         char ut_id[_UTX_IDSIZE];        /* inittab id */
                    110:         char ut_line[_UTX_LINESIZE];    /* tty name */
                    111:         char ut_host[_UTX_HOSTSIZE];    /* host name */
                    112:         uint16_t ut_session;            /* session id used for windowing */
                    113:         uint16_t ut_type;               /* type of this entry */
                    114:         pid_t ut_pid;                   /* process id creating the entry */
                    115:         struct {
                    116:                 uint16_t e_termination; /* process termination signal */
                    117:                 uint16_t e_exit;        /* process exit status */
                    118:         } ut_exit;
                    119:         struct sockaddr_storage ut_ss;  /* address where entry was made from */
                    120:         struct timeval ut_tv;           /* time entry was created */
                    121:         uint32_t ut_pad[10];            /* reserved for future use */
                    122: };
                    123: .Ed
                    124: .Pp
                    125: Valid entries for
                    126: .Fa ut_type
                    127: are:
                    128: .Bl -tag -width LOGIN_PROCESSXX -compact -offset indent
                    129: .It Dv BOOT_TIME
                    130: Time of a system boot.
                    131: .It Dv DEAD_PROCESS
                    132: A session leader exited.
                    133: .It Dv EMPTY
                    134: No valid user accounting information.
                    135: .It Dv INIT_PROCESS
                    136: A process spawned by
                    137: .Xr init 8 .
                    138: .It Dv LOGIN_PROCESS
                    139: The session leader of a logged-in user.
                    140: .It Dv NEW_TIME
                    141: Time after system clock change.
                    142: .It Dv OLD_TIME
                    143: Time before system clock change.
                    144: .It Dv RUN_LVL
                    145: Run level.
                    146: Provided for compatibility, not used on
1.3       wiz       147: .Nx .
1.1       wiz       148: .It Dv USER_PROCESS
                    149: A user process.
                    150: .El
                    151: .Sh RETURN VALUES
                    152: .Fn getutxent
                    153: returns the next entry, or
                    154: .Dv NULL
                    155: on failure (end of database or problems reading from the database).
                    156: .Fn getutxid
                    157: and
                    158: .Fn getutxline
                    159: return the matching structure on success, or
                    160: .Dv NULL
                    161: if no match was found.
                    162: .Fn pututxline
                    163: returns the structure that was successfully written, or
                    164: .Dv NULL .
                    165: .Sh SEE ALSO
                    166: .Xr logwtmpx 3 ,
                    167: .Xr utmpx 5
                    168: .Sh STANDARDS
                    169: The
1.4     ! atatat    170: .Fn endutxent ,
1.1       wiz       171: .Fn getutxent ,
                    172: .Fn getutxid ,
                    173: .Fn getutxline ,
                    174: .Fn pututxline ,
                    175: .Fn setutxent
                    176: all conform to
                    177: .St -p1003.1-2001
                    178: (XSI extension), and previously to
                    179: .St -xpg4.2 .
                    180: The fields
                    181: .Fa ut_user ,
                    182: .Fa ut_id ,
                    183: .Fa ut_line ,
                    184: .Fa ut_pid ,
                    185: .Fa ut_type ,
                    186: and
                    187: .Fa ut_tv
                    188: conform to
                    189: .St -p1003.1-2001
                    190: (XSI extension), and previously to
                    191: .St -xpg4.2 .
                    192: .\" .Fa ut_host ,
                    193: .\" .Fa ut_session ,
                    194: .\" .Fa ut_exit ,
                    195: .\" and
                    196: .\" .Fa ut_ss
                    197: .\" are from
                    198: .\" SVR3/4?
                    199: .\" .Dv RUN_LVL
                    200: .\" is for compatibility with
                    201: .\" what exactly?
                    202: .\" .Sh HISTORY
                    203: .\" The
                    204: .\" .Nm utmpx ,
                    205: .\" .Nm wtmpx ,
                    206: .\" and
                    207: .\" .Nm lastlogx
                    208: .\" files first appeared in
                    209: .\" SVR3? 4?