.Dd 10/25/15
.Dt netusage 1
.Os Darwin
.\"---------
.Sh NAME
.\"---------
.Nm netusage
.Nd Display traffic usage statistics about the network
.\"---------
.Sh SYNOPSIS
.\"---------
.Nm
.Op --help
.Nm
.Ar commands Op Ar arguments ...

.\"---------
.Sh DESCRIPTION
.\"---------
The
.Nm
program interfaces with
.Nm symptomsd
to display and manage network traffic usage statistics.
.Pp
As additional feature of this tool allows for looking up an application or
process name using a Mach-O UUID or a PID.
.\"---------
.Sh NETWORK STATISTICS COMMANDS
.\"---------
The following commands are used to provide different representations of
network traffic usage statistics collected on the system.
.Bl -tag -width -indent

.\"--all-traffic
.It Xo Cm --all-traffic
.Op -p
.Op -r
.Op -n Ar name
.Op -s Ar sortorder
.Op -d Ar importfile
.Op -e Ar exportfile
.Op --unitize
.Op --compact
.Op --interactive
.Op --interval Ar seconds
.Xc
Display a table listing the total ingress and egress network traffic usage for
each application or process categorized by interface. A timestamp of when the
first network traffic was observed is also shown. By default, only applications
will be shown unless the
.Cm -p
flag is provided.

.Bl -tag -width -indent
.It Xo -p
.Xc
Show a list that includes the combination of applications and processes.
.El

.Bl -tag -width -indent
.It Xo -r
.Xc
Force a database refresh before showing the list.
.El

.Bl -tag -width -indent
.It Xo -n Ar name
.Xc
Only show the application or process matching
.Ar name .
.El

.Bl -tag -width -indent
.It Xo -s Ar sortorder
.Xc
Sort the list according the following available sort orders:

.Bl -tag -width -indent
.It Xo Cm t
.Xc
Sort by total network usage. (default)
.El
.Bl -tag -width -indent
.It Xo Cm c
.Xc
Sort by cellular interface usage.
.El
.Bl -tag -width -indent
.It Xo Cm w
.Xc
Sort by wi-fi interface usage.
.El
.Bl -tag -width -indent
.It Xo Cm i
.Xc
Sort by wired interface usage.
.El
.Bl -tag -width -indent
.It Xo Cm a
.Xc
Sort by awdl interface usage.
.El
.Bl -tag -width -indent
.It Xo Cm e
.Xc
Sort by expensive interface usage.
.El
.El

.Bl -tag -width -indent
.It Xo -d Ar importfile
.Xc
Show a traffic usage comparison between the current values and the contents of
the file at
.Ar importfile .
.El

.Bl -tag -width -indent
.It Xo -e Ar exportfile
.Xc
Save the current traffic usage values into
.Ar exportfile .
.El

.Bl -tag -width -indent
.It Xo --unitize
.Xc
Show the table values in unitized format (eg. KB/MB/GB).
.El

.Bl -tag -width -indent
.It Xo --compact
.Xc
When showing a traffic usage comparison, only list the entries whose values
have changed.
.El

.Bl -tag -width -indent
.It Xo --interactive
.Xc
Show a traffic usage table that periodically refresh and can be viewed
interactively. When an update occurs, the usage value for the application or
process that generated network traffic will appear emphasized. You can use the
following commands to interact with the table.

.Bl -tag -width -indent
.It Xo Cm q
.Xc
Quit
.El
.Bl -tag -width -indent
.It Xo Cm p
.Xc
Toggles the values between showing raw bytes and unitized format
.El
.Bl -tag -width -indent
.It Xo Cm s
.Xc
Change the sort order of the columns
.El
.Bl -tag -width -indent
.It Xo Cm r
.Xc
Redraw the screen
.El
.Bl -tag -width -indent
.It Xo Cm h
.Xc
Show help
.El
.Bl -tag -width -indent
.It Xo Cm Arrow Keys
.Xc
Scroll the list
.El
.El

.Bl -tag -width -indent
.It Xo --interval Ar seconds
.Xc
Set the periodic refresh interval to the specified number of seconds. The
minimum value is 5 seconds, and the default interval is 15 seconds. (Only
valid in interactive mode)
.El

.\"---------
.Sh MANAGEMENT COMMANDS
.\"---------
These commands are used to manage and reset the collected network traffic usage
statistics.

.Bl -tag -width -indent

.\"--reset-entry
.It Xo Cm --reset-entry
.Op -p
.Op -n Ar name
.Xc
Reset the network traffic usage statistics stored for a single entry. Use the
.Cm -n
flag (and optionally the
.Cm -p
flag) to specify the name of the entry.
.Bl -tag -width -indent
.It Xo --unitize Ar name
.Xc
Specify the name of the application to reset the network usage statistics.
.El
.Bl -tag -width -indent
.It Xo -p
.Xc
Specify a process name instead of an application name.
.El

.\"--reset-all
.It Xo Cm --reset-all
.Xc
Reset the network traffic usage statistics for all the stored entries.

.\"---------
.Sh OTHER COMMANDS
.\"---------
These are optional utility commands that are available to look up applications
or processes.
.Bl -tag -width -indent

.\"--resolve-uuid
.It Xo Cm --resolve-uuid Ar uuid
.Xc
Resolve the given mach-O
.Ar uuid
into an application identifier.

.\"--resolve-pid
.It Xo Cm --resolve-pid
.Ar pid
.Xc
Resolve the given
.Ar pid
into an application identifier.

.El
.\"---------
.\" .Sh BUGS              \" Document known, unremedied bugs 
.\"---------
.\"---------
.\" .Sh HISTORY           \" Document history if command behaves in a unique manner
.\"---------