KYLIN-TIME(1)

NAME
kylin-time - run programs and summarize system resource usage (Rust rewrite)

SYNOPSIS

kylin-time
    [ -apqvV ] [ -f FORMAT ] [ -o FILE ]
    [ --append ] [ --verbose ] [ --quiet ] [ --portability ]
    [ --format=FORMAT ] [ --output=FILE ] [ --version ]
    [ --help ] COMMAND [ ARGS ]

DESCRIPTION
kylin-time runs the program COMMAND with any given arguments ARG.... When COMMAND finishes, kylin-time displays information about resources used by COMMAND (on the standard error output, by default). If COMMAND exits with non-zero status, kylin-time displays a warning message and the exit status. kylin-time determines which information to display about the resources used by the COMMAND from the string FORMAT. If no format is specified on the command line, but the TIME environment variable is set, its value is used as the format. Otherwise, a default format built into kylin-time is used. Options to kylin-time must appear on the command line before COMMAND. Anything on the command line after COMMAND is passed as arguments to COMMAND. kylin-time is a Rust rewrite of the GNU time utility, providing the same functionality with improved safety and reliability.

OPTIONS

-o FILE, --output=FILE
    Write the resource use statistics to FILE instead of to the standard error stream. By default, this overwrites the file, destroying the file's previous contents. This option is useful for collecting information on interactive programs and programs that produce output on the standard error stream.

-a, --append
    Append the resource use information to the output file instead of overwriting it. This option is only useful with the `-o' or `--output' option.

-f FORMAT, --format FORMAT
    Use FORMAT as the format string that controls the output of kylin-time. See the below for more information.

--help
    Print a summary of the command line options and exit.

-p, --portability
    Use the following format string, for conformance with POSIX standard 1003.2:
              real %e
              user %U
              sys %S

-v, --verbose
    Use the built-in verbose format, which displays each available piece of information on the program's resource use on its own line, with an English description of its meaning.

--quiet
    Do not report the status of the program even if it is different from zero.

-V, --version
    Print the version number of kylin-time and exit.

FORMATTING THE OUTPUT
The format string FORMAT controls the contents of the kylin-time output. The format string can be set using the `-f' or `--format', `-v' or `--verbose', or `-p' or `--portability' options. If they are not given, but the TIME environment variable is set, its value is used as the format string. Otherwise, a built-in default format is used. The default format is:
  %Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k
  %Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps The format string usually consists of `resource specifiers' interspersed with plain text. A percent sign (`%') in the format string causes the following character to be interpreted as a resource specifier, which is similar to the formatting characters in the printf(3) function. A backslash (`\') introduces a `backslash escape', which is translated into a single printing character upon output. `\t' outputs a tab character, `\n' outputs a newline, and `\\' outputs a backslash. A backslash followed by any other character outputs a question mark (`?') followed by a backslash, to indicate that an invalid backslash escape was given. Other text in the format string is copied verbatim to the output. kylin-time always prints a newline after printing the resource use information, so normally format strings do not end with a newline character (or `\n'). The resource specifiers, which are a superset of those recognized by the tcsh(1) builtin `time' command, are:
    %   A literal `%'.
    C   Name and command line arguments of the command being timed.
    D   Average size of the process's unshared data area, in Kilobytes.
    E   Elapsed real (wall clock) time used by the process, in [hours:]minutes:seconds.
    e   Elapsed real (wall clock) time used by the process, in seconds.
    F   Number of major, or I/O-requiring, page faults that occurred while the process was running.
    I   Number of file system inputs by the process.
    K   Average total (data+stack+text) memory use of the process, in Kilobytes.
    M   Maximum resident set size of the process during its lifetime, in Kilobytes.
    O   Number of file system outputs by the process.
    P   Percentage of the CPU that this job got (user + system times divided by total running time). Also prints a percentage sign.
    R   Number of minor, or recoverable, page faults.
    S   Total number of CPU-seconds used by the system on behalf of the process (in kernel mode), in seconds.
    U   Total number of CPU-seconds that the process used directly (in user mode), in seconds.
    W   Number of times the process was swapped out of main memory.
    X   Average amount of shared text in the process, in Kilobytes.
    Z   System's page size, in bytes.
    c   Number of times the process was context-switched involuntarily.
    k   Number of signals delivered to the process.
    p   Average unshared stack size of the process, in Kilobytes.
    r   Number of socket messages received by the process.
    s   Number of socket messages sent by the process.
    t   Average resident set size of the process, in Kilobytes.
    w   Number of times that the program was context-switched voluntarily.
    x   Exit status of the command.

EXAMPLES
To run the command `wc /etc/hosts' and show the default information:
     kylin-time wc /etc/hosts To run the command `ls -Fs' and show just the user, system, and total time:
     kylin-time -f "\t%E real,\t%U user,\t%S sys" ls -Fs To edit the file BORK and have `kylin-time' append the elapsed time and number of signals to the file `log', reading the format string from the environment variable `TIME':
     export TIME="\t%E,\t%k" # If using bash or ksh
     setenv TIME "\t%E,\t%k" # If using csh or tcsh
     kylin-time -a -o log emacs bork

DIAGNOSTICS
If the program exited normally, the return value of kylin-time is the return value of the program it executed and measured. Otherwise, the return value is 128 plus the number of the signal which caused the program to stop or terminate.

AUTHOR
kylin-time is a Rust rewrite of GNU time, originally written by David Keppel, David MacKenzie, and Assaf Gordon.

SEE ALSO
tcsh(1), printf(3), time(1)