list-logins 1 administrator commands nosh
list-logins login listing tool
`list-logins` --field name --time-format formatstring --no-init line(s)

## Description

`list-logins` is a tool for listing login information. Its output is machine-parseable and suitable for console-flat-table-viewer 1 with 1 header line and --format tabbed or awk 1 with -F'\t'.

The line command-line arguments are a filter set that is matched against the line names, enabling the selection of individual login records. If there are no line arguments, the entire list is output, unfiltered. It is not an error for a filter item not to match a line.

The --field command-line option specifies a list of fields by name. What exactly the fields are varies from operating system to operating system. There is a basic common set: line, user, host, and time.

The --time-format command-line option specifies an alternative display format to be employed for all time fields, formatstring, in the form employed by the strftime 3 library function.

The --no-init command-line option has no effect on most BSDs, where the concept is meaningless. On Linux-based operating systems, it excludes `INIT_PROCESS` and `LOGIN_PROCESS` records, login-process 1 and the programs that it is compatible with. With modern systems with modern system managers, this option is either meaningless or moot.

## Output

The output format is variable-length records terminated by LF containing TAB-separated fields. Fields are output as if passed through the BSD `vis` 3 library function. They are thus unambiguously machine-parseable, because any whitespace in the field itself is encoded by `vis` 3. After separating out an individual field, its contents can (for example) be decoded in shell script using the `unvis` 1 utility (which is supplied by FreeBSD).

The field names are transformed to uppercase for the initial header record.

## Examples

This command uses `list-logins` to produce similar output to who 1 with its -H option.

    $ list-logins --field name --field line --field time --field host |
    > awk '{ if (1 == NR) print; else printf "%s\t%s\t%s\t(%s)\n",$1,$2,$3,$4; }' |
    > unvis

This command uses `list-logins` to display a continually updated table similar to who 1 with its -H option.

    $ while list-logins --field pid --field name --field line --field time --field host |
    > awk '{ if ( 2 > NR ) printf "\f%s\n",$0; else printf "%s\t%s\t%s\t%s\t%s\t(%s)\n",$1,$2,$3,$4,$5,$6; }'
    > do
    >     sleep 5
    > done |
    > console-flat-table-viewer --format tabbed --header-count 1

## Author

Jonathan de Boyne Pollard