Decoded: users (coreutils)

[Back to Project Main Page]

Note: This page explores the design of command-line utilities. It is not a user guide.
[GNU Manual] [No POSIX requirement] [Linux man] [FreeBSD man]

Logical flow of users command (coreutils)

Summary

users - print login names of users currently logged in

[Source] [Code Walkthrough]

Lines of code: 158
Principal syscall: None
Support syscalls: None
Options: 2 (help and version)

This is originally a GNU utility with distinct functionality from who
Added to Shellutils in July 1997 [First version]
Number of revisions: 75

Helpers:
  • userid_compare() - Simple string compare
  • list_entries_users() - Buffer logins, sort by name, output list
  • users() - Processes system users using the provided file
External non-standard helpers:
  • error() - Outputs error message to standard error with possible process termination
  • read_utmp() - Processes the utmp file in to the provided buffer. (from gnulib)
  • extract_trimmed_name() - Get the user name, spaces removed and NUL-termed

Setup

users only checks the default parsing options, which require no initialization. main() initializes no extra variables.

Parsing

Parsing only checks for the two standard options for help and version. Users may pass an argument on the command line interpreated as the utmp file to process.

Parsing failures

This failure case is explicitly checked:

  • If any non-long operand is passed
  • Multiple arguments beyond the single expected utmp

This failure result in a short error message followed by the usage instructions.

Execution

The users execution flow looks like this:

  • Process the provided utmp file with read_utmp()
  • Buffer each entry with a trimmed user name
  • Sort the buffer
  • Print each entry from the buffer

The single failure happens if the utmp file cannot be accessed

Extra comments

The default utmp file should be known to coreutils via readutmp.h (utmpx.h). It is typically found in /var

[Back to Project Main Page]