Read Me About UTXplorer

=======================

1.0

UTXplorer demonstrates basic use of the <utmpx.h> API <x-man-page://3/getutxent> that was introduced in Mac OS X 10.5 as a replacement for the "utmp", "wtmp" and "lastlog" files <x-man-page://5/utmp>.  You can use this API to determine which users are logged into the machine and get a historical records of logins and logouts.  Commands like <x-man-page://1/who> and <x-man-page://1/last> are based on this API.

This sample requires Mac OS X 10.5 (or later) because the <utmpx.h> API was introduced in that release.

Packing List

------------

The sample contains the following items:

o Read Me About Read Me About UTXplorer.txt -- This file.

o UTXplorer.c -- C source code for the program.

o UTXplorer.xcodeproj -- An Xcode 3.0 project for the program.

o build -- A directory containing a pre-built binary.

Using the Sample

----------------

The sample has a number of different commands.  Run the sample with no arguments to see them all:

$ build/Debug/UTXplorer

usage: UTXplorer command [options] [arguments]

    commands:

        getutxent      [-v] [-w] [-a] [-t type]...

        getutxent_wtmp [-v] [-w] [-a] [-t type]...

            options:

            [...]

        getlastlogx uid

        getlastlogxbyname username

The "getlastlogx" and "getlastlogxbyname" commands are trivial.  Just run them with a user ID and user name, respectively, to see the last time that user logged in:

$ build/Debug/UTXplorer getlastlogx 501

time                     line             host

----                     ----             ----

2008-02-29 12:27:10 GMT  ttys005          

$ build/Debug/UTXplorer getlastlogxbyname god

time                     line             host

----                     ----             ----

2008-02-29 12:27:10 GMT  ttys005          

The "getutxent" command displays the events in the 'utmp' database, that is, the list of users that are currently logged in.

$ build/Debug/UTXplorer getutxent

time                     type          id   pid   user             line   [...]

----                     ----          --   ---   ----             ----   [...]

2008-02-11 14:05:47 GMT  BOOT_TIME                                                  

2008-02-11 14:12:07 GMT  USER_PROCESS  /    47    quinn            console          

2008-02-29 12:00:42 GMT  USER_PROCESS  s001 41234 quinn            ttys001          

2008-02-29 12:43:21 GMT  USER_PROCESS  s005 42417 mrgumby          ttys005          

If you supply the "-w" option, the command will watch for changes to the state and display them as they happen.  The "-t xxx" option lets you specify exactly which type of events to report.  The "-a" option is a short cut way to request all event types.  The "-v" option requests increasing levels of verbosity.

$ build/Debug/UTXplorer getutxent -w

time                     type          id   pid   user             line   [...]

----                     ----          --   ---   ----             ----   [...]

2008-02-11 14:05:47 GMT  BOOT_TIME                                                  

2008-02-11 14:12:07 GMT  USER_PROCESS  /    47    quinn            console          

2008-02-29 12:00:42 GMT  USER_PROCESS  s001 41234 quinn            ttys001          

2008-02-29 12:43:21 GMT  USER_PROCESS  s005 42417 mrgumby          ttys005          

[... after logging out mrgumby ...]

2008-02-29 12:44:46 GMT  DEAD_PROCESS  s005 42417                                   

^C

Use the "getutxent_wtmp" command to view the 'wtmp' database, that is, a historical record of login and logout events.

$ build/Debug/UTXplorer getutxent_wtmp

[... lots of output ...]

This supports the same set of options as the "getutxent" command, most notably the "-w" option to watch for new events.

Building the Sample

-------------------

The sample was built using Xcode 3.0 on Mac OS X 10.5.  You should be able to just open the project and choose Build from the Build menu.  This will build the UTXplorer tool in the "build" directory.

How it Works

------------

The "getlastlogx" and "getlastlogxbyname" commands are trivial wrappers around the APIs of the same name.

The "getutxent" and "getutxent_wtmp" commands are significantly more complex.  They share a common implementation.  This code iterates the relevant database (using either getutxent or getutxent_wtmp) and prints the results.  If the "-w" option is specified, it waits for changes to the database (courtesy of the <x-man-page://3/notify> API) and prints any new events.

Caveats

-------

The <utmpx.h> API is not thread safe.

The 'utmp' database tracks non-GUI logins on tty-by-tty basis.  It gets confused if two people log in via the same tty (for example, by running <x-man-page://1/login> manually) <rdar://problem/5771077>.

Credits and Version History

---------------------------

If you find any problems with this sample, mail <dts@apple.com> and I'll try to fix them up.

1.0 (Mar 2008) was the first shipping version.

Share and Enjoy.

Apple Developer Technical Support

Core OS/Hardware

10 Mar 2008