1228 lines
57 KiB
HTML
1228 lines
57 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<!-- This manual is for GNU time command for running programs
|
|
and summarizing the system resources they use.
|
|
version UNKNOWN
|
|
updated 25 March 2022
|
|
|
|
Copyright (C) 1991-2018 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
|
Texts. A copy of the license is included in the section entitled
|
|
"GNU Free Documentation License". -->
|
|
<title>Measuring Program Resource Use</title>
|
|
|
|
<meta name="description" content="Measuring Program Resource Use">
|
|
<meta name="keywords" content="Measuring Program Resource Use">
|
|
<meta name="resource-type" content="document">
|
|
<meta name="distribution" content="global">
|
|
<meta name="Generator" content="makeinfo">
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|
|
|
<link href="#Top" rel="start" title="Top">
|
|
<link href="#Concept-index" rel="index" title="Concept index">
|
|
<link href="#SEC_Contents" rel="contents" title="Table of Contents">
|
|
<link href="#Resource-Measurement" rel="next" title="Resource Measurement">
|
|
<style type="text/css">
|
|
<!--
|
|
a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
|
|
a.summary-letter {text-decoration: none}
|
|
blockquote.indentedblock {margin-right: 0em}
|
|
div.display {margin-left: 3.2em}
|
|
div.example {margin-left: 3.2em}
|
|
kbd {font-style: oblique}
|
|
pre.display {font-family: inherit}
|
|
pre.format {font-family: inherit}
|
|
pre.menu-comment {font-family: serif}
|
|
pre.menu-preformatted {font-family: serif}
|
|
span.nolinebreak {white-space: nowrap}
|
|
span.roman {font-family: initial; font-weight: normal}
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
|
span:hover a.copiable-anchor {visibility: visible}
|
|
ul.no-bullet {list-style: none}
|
|
-->
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body lang="en">
|
|
<h1 class="settitle" align="center">Measuring Program Resource Use</h1>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="top" id="Top">
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="#Resource-Measurement" accesskey="n" rel="next">Measuring Program Resource Use</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<span id="Time"></span><h1 class="top">Time</h1>
|
|
|
|
<p>This file documents the the GNU <code>time</code> command for running programs
|
|
and summarizing the system resources they use.
|
|
Version UNKNOWN, updated 25 March 2022
|
|
</p>
|
|
|
|
|
|
<div class="Contents_element" id="SEC_Contents">
|
|
<h2 class="contents-heading">Table of Contents</h2>
|
|
|
|
<div class="contents">
|
|
|
|
<ul class="no-bullet">
|
|
<li><a id="toc-Measuring-Program-Resource-Use" href="#Resource-Measurement">1 Measuring Program Resource Use</a>
|
|
<ul class="no-bullet">
|
|
<li><a id="toc-Setting-the-Output-Format" href="#Setting-Format">1.1 Setting the Output Format</a></li>
|
|
<li><a id="toc-The-Format-String" href="#Format-String">1.2 The Format String</a>
|
|
<ul class="no-bullet">
|
|
<li><a id="toc-Time-Resources-1" href="#Time-Resources">1.2.1 Time Resources</a></li>
|
|
<li><a id="toc-Memory-Resources-1" href="#Memory-Resources">1.2.2 Memory Resources</a></li>
|
|
<li><a id="toc-I_002fO-Resources-1" href="#I_002fO-Resources">1.2.3 I/O Resources</a></li>
|
|
<li><a id="toc-Command-Info-1" href="#Command-Info">1.2.4 Command Info</a></li>
|
|
</ul></li>
|
|
<li><a id="toc-Redirecting-Output" href="#Redirecting">1.3 Redirecting Output</a></li>
|
|
<li><a id="toc-Examples-1" href="#Examples">1.4 Examples</a></li>
|
|
<li><a id="toc-Accuracy-1" href="#Accuracy">1.5 Accuracy</a></li>
|
|
<li><a id="toc-Running-the-time-Command" href="#Invoking-time">1.6 Running the <code>time</code> Command</a></li>
|
|
</ul></li>
|
|
<li><a id="toc-Reporting-bugs-1" href="#Reporting-bugs">2 Reporting bugs</a></li>
|
|
<li><a id="toc-GNU-Free-Documentation-License-1" href="#GNU-Free-Documentation-License">Appendix A GNU Free Documentation License</a></li>
|
|
<li><a id="toc-Concept-index-1" href="#Concept-index" rel="index">Concept index</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="chapter" id="Resource-Measurement">
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="#Reporting-bugs" accesskey="n" rel="next">Reporting bugs</a>, Previous: <a href="#Top" accesskey="p" rel="prev">Time</a>, Up: <a href="#Top" accesskey="u" rel="up">Time</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<span id="Measuring-Program-Resource-Use"></span><h2 class="chapter">1 Measuring Program Resource Use</h2>
|
|
<span id="index-time"></span>
|
|
<span id="index-time-1"></span>
|
|
<span id="index-time-2"></span>
|
|
<span id="index-measurement"></span>
|
|
|
|
<p>The <code>time</code> command runs another program, then displays information
|
|
about the resources used by that program, collected by the system while
|
|
the program was running. You can select which information is reported
|
|
and the format in which it is shown (see <a href="#Setting-Format">Setting the Output Format</a>), or have
|
|
<code>time</code> save the information in a file instead of displaying it on the
|
|
screen (see <a href="#Redirecting">Redirecting Output</a>).
|
|
</p>
|
|
<p>The resources that <code>time</code> can report on fall into the general
|
|
categories of time, memory, and I/O and IPC calls. Some systems do not
|
|
provide much information about program resource use; <code>time</code>
|
|
reports unavailable information as zero values (see <a href="#Accuracy">Accuracy</a>).
|
|
</p>
|
|
<p>The format of the <code>time</code> command is:
|
|
</p>
|
|
<div class="example">
|
|
<pre class="example">time <span class="roman">[</span>option…<span class="roman">]</span> <var>command</var> <span class="roman">[</span><var>arg</var>…<span class="roman">]</span>
|
|
</pre></div>
|
|
|
|
<span id="index-resources"></span>
|
|
<p><code>time</code> runs the program <var>command</var>, with any given arguments
|
|
<var>arg</var>…. When <var>command</var> finishes, <code>time</code> displays
|
|
information about resources used by <var>command</var>.
|
|
</p>
|
|
<p>Here is an example of using <code>time</code> to measure the time and other
|
|
resources used by running the program <code>grep</code>:
|
|
</p>
|
|
<div class="example">
|
|
<pre class="example">eg$ time grep nobody /etc/aliases
|
|
nobody:/dev/null
|
|
etc-files:nobody
|
|
misc-group:nobody
|
|
0.07user 0.50system 0:06.69elapsed 8%CPU (0avgtext+489avgdata 324maxresident)k
|
|
46inputs+7outputs (43major+251minor)pagefaults 0swaps
|
|
</pre></div>
|
|
|
|
<p>Mail suggestions and bug reports for GNU <code>time</code> to
|
|
<code>bug-time@gnu.org</code>. Please include the version of
|
|
<code>time</code>, which you can get by running ‘<samp>time --version</samp>’, and the
|
|
operating system and C compiler you used.
|
|
</p>
|
|
|
|
<ul class="section-toc">
|
|
<li><a href="#Setting-Format" accesskey="1">Setting the Output Format</a></li>
|
|
<li><a href="#Format-String" accesskey="2">The Format String</a></li>
|
|
<li><a href="#Redirecting" accesskey="3">Redirecting Output</a></li>
|
|
<li><a href="#Examples" accesskey="4">Examples</a></li>
|
|
<li><a href="#Accuracy" accesskey="5">Accuracy</a></li>
|
|
<li><a href="#Invoking-time" accesskey="6">Running the <code>time</code> Command</a></li>
|
|
</ul>
|
|
<hr>
|
|
<div class="section" id="Setting-Format">
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="#Format-String" accesskey="n" rel="next">The Format String</a>, Up: <a href="#Resource-Measurement" accesskey="u" rel="up">Measuring Program Resource Use</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<span id="Setting-the-Output-Format"></span><h3 class="section">1.1 Setting the Output Format</h3>
|
|
|
|
<p><code>time</code> uses a <em>format string</em> to determine which information to
|
|
display about the resources used by the command it runs. See <a href="#Format-String">The Format String</a>, for the interpretation of the format string contents.
|
|
</p>
|
|
<p>You can specify a format string with the command line options listed
|
|
below. If no format is specified on the command line, but the
|
|
<code>TIME</code> environment variable is set, its value is used as the format
|
|
string. Otherwise, the default format built into <code>time</code> is used:
|
|
</p>
|
|
<div class="example">
|
|
<pre class="example">%Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k
|
|
%Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps
|
|
</pre></div>
|
|
|
|
<p>The command line options to set the format are:
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><span><code>-f <var>format</var></code></span></dt>
|
|
<dt><span><code>--format=<var>format</var></code></span></dt>
|
|
<dd><p>Use <var>format</var> as the format string.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>-p</code></span></dt>
|
|
<dt><span><code>--portability</code></span></dt>
|
|
<dd><p>Use the following format string:
|
|
</p>
|
|
<div class="example">
|
|
<pre class="example">real %e
|
|
user %U
|
|
sys %S
|
|
</pre></div>
|
|
|
|
<p>The default output format of time differs widely between
|
|
implementations. This option (in its short form -p) is supported by all
|
|
POSIX-compliant ’time’ implementations to retrieve basic information in
|
|
the described format.
|
|
</p>
|
|
</dd>
|
|
<dt id='index-format'><span><code>-v</code><a href='#index-format' class='copiable-anchor'> ¶</a></span></dt>
|
|
<dt><span><code>--verbose</code></span></dt>
|
|
<dd><p>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.
|
|
</p></dd>
|
|
</dl>
|
|
|
|
<hr>
|
|
</div>
|
|
<div class="section" id="Format-String">
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="#Redirecting" accesskey="n" rel="next">Redirecting Output</a>, Previous: <a href="#Setting-Format" accesskey="p" rel="prev">Setting the Output Format</a>, Up: <a href="#Resource-Measurement" accesskey="u" rel="up">Measuring Program Resource Use</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<span id="The-Format-String"></span><h3 class="section">1.2 The Format String</h3>
|
|
|
|
<span id="index-format-1"></span>
|
|
<span id="index-resource"></span>
|
|
<p>The <em>format string</em> controls the contents of the <code>time</code> output.
|
|
It consists of <em>resource specifiers</em> and <em>escapes</em>, interspersed
|
|
with plain text.
|
|
</p>
|
|
<p>A backslash introduces an <em>escape</em>, which is translated
|
|
into a single printing character upon output. The valid escapes are
|
|
listed below. An invalid escape is output as a question mark followed
|
|
by a backslash.
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><span><code>\t</code></span></dt>
|
|
<dd><p>a tab character
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>\n</code></span></dt>
|
|
<dd><p>a newline
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>\\</code></span></dt>
|
|
<dd><p>a literal backslash
|
|
</p></dd>
|
|
</dl>
|
|
|
|
<p><code>time</code> always prints a newline after printing the resource use
|
|
information, so normally format strings do not end with a newline
|
|
character (or ‘<samp>\n</samp>’).
|
|
</p>
|
|
<p>A resource specifier consists of a percent sign followed by another
|
|
character. An invalid resource specifier is output as a question mark
|
|
followed by the invalid character. Use ‘<samp>%%</samp>’ to output a literal
|
|
percent sign.
|
|
</p>
|
|
<p>The resource specifiers, which are a superset of those recognized by the
|
|
<code>tcsh</code> builtin <code>time</code> command, are listed below. Not all
|
|
resources are measured by all versions of Unix, so some of the values
|
|
might be reported as zero (see <a href="#Accuracy">Accuracy</a>).
|
|
</p>
|
|
|
|
<ul class="section-toc">
|
|
<li><a href="#Time-Resources" accesskey="1">Time Resources</a></li>
|
|
<li><a href="#Memory-Resources" accesskey="2">Memory Resources</a></li>
|
|
<li><a href="#I_002fO-Resources" accesskey="3">I/O Resources</a></li>
|
|
<li><a href="#Command-Info" accesskey="4">Command Info</a></li>
|
|
</ul>
|
|
<hr>
|
|
<div class="subsection" id="Time-Resources">
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="#Memory-Resources" accesskey="n" rel="next">Memory Resources</a>, Up: <a href="#Format-String" accesskey="u" rel="up">The Format String</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<span id="Time-Resources-1"></span><h4 class="subsection">1.2.1 Time Resources</h4>
|
|
|
|
<dl compact="compact">
|
|
<dt><span><code>E</code></span></dt>
|
|
<dd><p>Elapsed real (wall clock) time used by the process, in
|
|
[hours:]minutes:seconds.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>e</code></span></dt>
|
|
<dd><p>Elapsed real (wall clock) time used by the process, in
|
|
seconds.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>S</code></span></dt>
|
|
<dd><p>Total number of CPU-seconds used by the system on behalf of the process
|
|
(in kernel mode), in seconds.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>U</code></span></dt>
|
|
<dd><p>Total number of CPU-seconds that the process used directly (in user
|
|
mode), in seconds.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>P</code></span></dt>
|
|
<dd><p>Percentage of the CPU that this job got. This is just user + system
|
|
times divied by the total running time.
|
|
</p></dd>
|
|
</dl>
|
|
|
|
<hr>
|
|
</div>
|
|
<div class="subsection" id="Memory-Resources">
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="#I_002fO-Resources" accesskey="n" rel="next">I/O Resources</a>, Previous: <a href="#Time-Resources" accesskey="p" rel="prev">Time Resources</a>, Up: <a href="#Format-String" accesskey="u" rel="up">The Format String</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<span id="Memory-Resources-1"></span><h4 class="subsection">1.2.2 Memory Resources</h4>
|
|
|
|
<dl compact="compact">
|
|
<dt><span><code>M</code></span></dt>
|
|
<dd><p>Maximum resident set size of the process during its lifetime, in
|
|
Kilobytes.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>t</code></span></dt>
|
|
<dd><p>Average resident set size of the process, in Kilobytes.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>K</code></span></dt>
|
|
<dd><p>Average total (data+stack+text) memory use of the process, in Kilobytes.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>D</code></span></dt>
|
|
<dd><p>Average size of the process’s unshared data area, in Kilobytes.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>p</code></span></dt>
|
|
<dd><p>Average size of the process’s unshared stack, in Kilobytes.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>X</code></span></dt>
|
|
<dd><p>Average size of the process’s shared text, in Kilobytes.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>Z</code></span></dt>
|
|
<dd><p>System’s page size, in bytes. This is a per-system constant, but
|
|
varies between systems.
|
|
</p></dd>
|
|
</dl>
|
|
|
|
<hr>
|
|
</div>
|
|
<div class="subsection" id="I_002fO-Resources">
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="#Command-Info" accesskey="n" rel="next">Command Info</a>, Previous: <a href="#Memory-Resources" accesskey="p" rel="prev">Memory Resources</a>, Up: <a href="#Format-String" accesskey="u" rel="up">The Format String</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<span id="I_002fO-Resources-1"></span><h4 class="subsection">1.2.3 I/O Resources</h4>
|
|
|
|
<dl compact="compact">
|
|
<dt><span><code>F</code></span></dt>
|
|
<dd><p>Number of major, or I/O-requiring, page faults that occurred while the
|
|
process was running. These are faults where the page has actually
|
|
migrated out of primary memory.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>R</code></span></dt>
|
|
<dd><p>Number of minor, or recoverable, page faults. These are pages that are
|
|
not valid (so they fault) but which have not yet been claimed by other
|
|
virtual pages. Thus the data in the page is still valid but the system
|
|
tables must be updated.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>W</code></span></dt>
|
|
<dd><p>Number of times the process was swapped out of main memory.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>c</code></span></dt>
|
|
<dd><p>Number of times the process was context-switched involuntarily (because
|
|
the time slice expired).
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>w</code></span></dt>
|
|
<dd><p>Number of times that the program was context-switched voluntarily, for
|
|
instance while waiting for an I/O operation to complete.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>I</code></span></dt>
|
|
<dd><p>Number of file system inputs by the process.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>O</code></span></dt>
|
|
<dd><p>Number of file system outputs by the process.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>r</code></span></dt>
|
|
<dd><p>Number of socket messages received by the process.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>s</code></span></dt>
|
|
<dd><p>Number of socket messages sent by the process.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>k</code></span></dt>
|
|
<dd><p>Number of signals delivered to the process.
|
|
</p></dd>
|
|
</dl>
|
|
|
|
<hr>
|
|
</div>
|
|
<div class="subsection" id="Command-Info">
|
|
<div class="header">
|
|
<p>
|
|
Previous: <a href="#I_002fO-Resources" accesskey="p" rel="prev">I/O Resources</a>, Up: <a href="#Format-String" accesskey="u" rel="up">The Format String</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<span id="Command-Info-1"></span><h4 class="subsection">1.2.4 Command Info</h4>
|
|
|
|
<dl compact="compact">
|
|
<dt><span><code>C</code></span></dt>
|
|
<dd><p>Name and command line arguments of the command being timed.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>x</code></span></dt>
|
|
<dd><p>Exit status of the command.
|
|
</p></dd>
|
|
</dl>
|
|
|
|
<hr>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="Redirecting">
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="#Examples" accesskey="n" rel="next">Examples</a>, Previous: <a href="#Format-String" accesskey="p" rel="prev">The Format String</a>, Up: <a href="#Resource-Measurement" accesskey="u" rel="up">Measuring Program Resource Use</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<span id="Redirecting-Output"></span><h3 class="section">1.3 Redirecting Output</h3>
|
|
|
|
<p>By default, <code>time</code> writes the resource use statistics to the
|
|
standard error stream. The options below make it write the statistics
|
|
to a file instead. Doing this can be useful if the program you’re
|
|
running writes to the standard error or you’re running <code>time</code>
|
|
noninteractively or in the background.
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><span><code>-o <var>file</var></code></span></dt>
|
|
<dt><span><code>--output=<var>file</var></code></span></dt>
|
|
<dd><p>Write the resource use statistics to <var>file</var>. By default, this
|
|
<em>overwrites</em> the file, destroying the file’s previous contents.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>-a</code></span></dt>
|
|
<dt><span><code>--append</code></span></dt>
|
|
<dd><p><em>Append</em> the resource use information to the output file instead
|
|
of overwriting it. This option is only useful with the ‘<samp>-o</samp>’ or
|
|
‘<samp>--output</samp>’ option.
|
|
</p></dd>
|
|
</dl>
|
|
|
|
<hr>
|
|
</div>
|
|
<div class="section" id="Examples">
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="#Accuracy" accesskey="n" rel="next">Accuracy</a>, Previous: <a href="#Redirecting" accesskey="p" rel="prev">Redirecting Output</a>, Up: <a href="#Resource-Measurement" accesskey="u" rel="up">Measuring Program Resource Use</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<span id="Examples-1"></span><h3 class="section">1.4 Examples</h3>
|
|
|
|
<p>Run the command ‘<samp>wc /etc/hosts</samp>’ and show the default information:
|
|
</p>
|
|
<div class="example">
|
|
<pre class="example">eg$ time wc /etc/hosts
|
|
35 111 1134 /etc/hosts
|
|
0.00user 0.01system 0:00.04elapsed 25%CPU (0avgtext+0avgdata 0maxresident)k
|
|
1inputs+1outputs (0major+0minor)pagefaults 0swaps
|
|
</pre></div>
|
|
|
|
<p>Run the command ‘<samp>ls -Fs</samp>’ and show just the user, system, and
|
|
wall-clock time:
|
|
</p>
|
|
<div class="example">
|
|
<pre class="example">eg$ time -f "\t%E real,\t%U user,\t%S sys" ls -Fs
|
|
total 16
|
|
1 account/ 1 db/ 1 mail/ 1 run/
|
|
1 backups/ 1 emacs/ 1 msgs/ 1 rwho/
|
|
1 crash/ 1 games/ 1 preserve/ 1 spool/
|
|
1 cron/ 1 log/ 1 quotas/ 1 tmp/
|
|
0:00.03 real, 0.00 user, 0.01 sys
|
|
</pre></div>
|
|
|
|
<p>Edit the file <samp>.bashrc</samp> and have <code>time</code> append the elapsed time
|
|
and number of signals to the file <samp>log</samp>, reading the format string
|
|
from the environment variable <code>TIME</code>:
|
|
</p>
|
|
<div class="example">
|
|
<pre class="example">eg$ export TIME="\t%E,\t%k" #<span class="roman"> If using bash or ksh</span>
|
|
eg$ setenv TIME "\t%E,\t%k" #<span class="roman"> If using csh or tcsh</span>
|
|
eg$ time -a -o log emacs .bashrc
|
|
eg$ cat log
|
|
0:16.55, 726
|
|
</pre></div>
|
|
|
|
<p>Run the command ‘<samp>sleep 4</samp>’ and show all of the information about it
|
|
verbosely:
|
|
</p>
|
|
<div class="example">
|
|
<pre class="example">eg$ time -v sleep 4
|
|
Command being timed: "sleep 4"
|
|
User time (seconds): 0.00
|
|
System time (seconds): 0.05
|
|
Percent of CPU this job got: 1%
|
|
Elapsed (wall clock) time (h:mm:ss or m:ss): 0:04.26
|
|
Average shared text size (kbytes): 36
|
|
Average unshared data size (kbytes): 24
|
|
Average stack size (kbytes): 0
|
|
Average total size (kbytes): 60
|
|
Maximum resident set size (kbytes): 32
|
|
Average resident set size (kbytes): 24
|
|
Major (requiring I/O) page faults: 3
|
|
Minor (reclaiming a frame) page faults: 0
|
|
Voluntary context switches: 11
|
|
Involuntary context switches: 0
|
|
Swaps: 0
|
|
File system inputs: 3
|
|
File system outputs: 1
|
|
Socket messages sent: 0
|
|
Socket messages received: 0
|
|
Signals delivered: 1
|
|
Page size (bytes): 4096
|
|
Exit status: 0
|
|
</pre></div>
|
|
|
|
<hr>
|
|
</div>
|
|
<div class="section" id="Accuracy">
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="#Invoking-time" accesskey="n" rel="next">Running the <code>time</code> Command</a>, Previous: <a href="#Examples" accesskey="p" rel="prev">Examples</a>, Up: <a href="#Resource-Measurement" accesskey="u" rel="up">Measuring Program Resource Use</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<span id="Accuracy-1"></span><h3 class="section">1.5 Accuracy</h3>
|
|
<span id="index-error-_0028in-measurement_0029"></span>
|
|
|
|
<p>The elapsed time is not collected atomically with the execution of the
|
|
program; as a result, in bizarre circumstances (if the <code>time</code>
|
|
command gets stopped or swapped out in between when the program being
|
|
timed exits and when <code>time</code> calculates how long it took to run), it
|
|
could be much larger than the actual execution time.
|
|
</p>
|
|
<p>When the running time of a command is very nearly zero, some values
|
|
(e.g., the percentage of CPU used) may be reported as either zero (which
|
|
is wrong) or a question mark.
|
|
</p>
|
|
<p>Most information shown by <code>time</code> is derived from the <code>wait3</code>
|
|
system call. The numbers are only as good as those returned by
|
|
<code>wait3</code>. Many systems do not measure all of the resources that
|
|
<code>time</code> can report on; those resources are reported as zero. The
|
|
systems that measure most or all of the resources are based on 4.2 or
|
|
4.3BSD. Later BSD releases use different memory management code that
|
|
measures fewer resources.
|
|
</p>
|
|
<p>On systems that do not have a <code>wait3</code> call that returns status
|
|
information, the <code>times</code> system call is used instead. It provides
|
|
much less information than <code>wait3</code>, so on those systems <code>time</code>
|
|
reports most of the resources as zero.
|
|
</p>
|
|
<p>The ‘<samp>%I</samp>’ and ‘<samp>%O</samp>’ values are allegedly only “real” input
|
|
and output and do not include those supplied by caching devices. The
|
|
meaning of “real” I/O reported by ‘<samp>%I</samp>’ and ‘<samp>%O</samp>’ may be
|
|
muddled for workstations, especially diskless ones.
|
|
</p>
|
|
<hr>
|
|
</div>
|
|
<div class="section" id="Invoking-time">
|
|
<div class="header">
|
|
<p>
|
|
Previous: <a href="#Accuracy" accesskey="p" rel="prev">Accuracy</a>, Up: <a href="#Resource-Measurement" accesskey="u" rel="up">Measuring Program Resource Use</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<span id="Running-the-time-Command"></span><h3 class="section">1.6 Running the <code>time</code> Command</h3>
|
|
|
|
<p>The format of the <code>time</code> command is:
|
|
</p>
|
|
<div class="example">
|
|
<pre class="example">time <span class="roman">[</span>option…<span class="roman">]</span> <var>command</var> <span class="roman">[</span><var>arg</var>…<span class="roman">]</span>
|
|
</pre></div>
|
|
|
|
<span id="index-resources-1"></span>
|
|
<p><code>time</code> runs the program <var>command</var>, with any given arguments
|
|
<var>arg</var>…. When <var>command</var> finishes, <code>time</code> displays
|
|
information about resources used by <var>command</var> (on the standard error
|
|
output, by default). If <var>command</var> exits with non-zero status or is
|
|
terminated by a signal, <code>time</code> displays a warning message and the
|
|
exit status or signal number.
|
|
</p>
|
|
<p>Options to <code>time</code> must appear on the command line before
|
|
<var>command</var>. Anything on the command line after <var>command</var> is
|
|
passed as arguments to <var>command</var>.
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><span><code>-o <var>file</var></code></span></dt>
|
|
<dt><span><code>--output=<var>file</var></code></span></dt>
|
|
<dd><p>Write the resource use statistics to <var>file</var>.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>-a</code></span></dt>
|
|
<dt><span><code>--append</code></span></dt>
|
|
<dd><p><em>Append</em> the resource use information to the output file instead
|
|
of overwriting it.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>-f <var>format</var></code></span></dt>
|
|
<dt><span><code>--format=<var>format</var></code></span></dt>
|
|
<dd><p>Use <var>format</var> as the format string.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>--help</code></span></dt>
|
|
<dd><p>Print a summary of the command line options to <code>time</code> and exit.
|
|
</p>
|
|
</dd>
|
|
<dt><span><code>-p</code></span></dt>
|
|
<dt><span><code>--portability</code></span></dt>
|
|
<dd><p>Use the POSIX format.
|
|
</p>
|
|
</dd>
|
|
<dt id='index-format-2'><span><code>-v</code><a href='#index-format-2' class='copiable-anchor'> ¶</a></span></dt>
|
|
<dt><span><code>--verbose</code></span></dt>
|
|
<dd><p>Use the built-in verbose format.
|
|
</p>
|
|
</dd>
|
|
<dt id='index-version-number'><span><code>-V</code><a href='#index-version-number' class='copiable-anchor'> ¶</a></span></dt>
|
|
<dt><span><code>--version</code></span></dt>
|
|
<dd><p>Print the version number of <code>time</code> and exit.
|
|
</p></dd>
|
|
</dl>
|
|
|
|
|
|
|
|
<hr>
|
|
</div>
|
|
</div>
|
|
<div class="chapter" id="Reporting-bugs">
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="#GNU-Free-Documentation-License" accesskey="n" rel="next">GNU Free Documentation License</a>, Previous: <a href="#Resource-Measurement" accesskey="p" rel="prev">Measuring Program Resource Use</a>, Up: <a href="#Top" accesskey="u" rel="up">Time</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<span id="Reporting-bugs-1"></span><h2 class="chapter">2 Reporting bugs</h2>
|
|
|
|
<span id="index-bug-reporting"></span>
|
|
<span id="index-problems"></span>
|
|
<span id="index-reporting-bugs"></span>
|
|
|
|
<p>To report bugs, suggest enhancements or otherwise discuss GNU Datamash,
|
|
please send electronic mail to <a href="mailto:bug-time.org">bug-time.org</a>.
|
|
</p>
|
|
<span id="index-checklist-for-bug-reports"></span>
|
|
<p>For bug reports, please include enough information for the maintainers
|
|
to reproduce the problem. Generally speaking, that means:
|
|
</p>
|
|
<ul>
|
|
<li> The version numbers of Datamash (which you can find by running
|
|
‘<samp>time <span class="nolinebreak">--version</span></samp>’<!-- /@w -->) and any other program(s) or
|
|
manual(s) involved.
|
|
</li><li> Hardware and operating system names and versions.
|
|
</li><li> The contents of any input files necessary to reproduce the bug.
|
|
</li><li> The expected behavior and/or output.
|
|
</li><li> A description of the problem and samples of any erroneous output.
|
|
</li><li> Options you gave to <code>configure</code> other than specifying
|
|
installation directories.
|
|
</li><li> Anything else that you think would be helpful.
|
|
</li></ul>
|
|
|
|
<p>When in doubt whether something is needed or not, include it. It’s
|
|
better to include too much than to leave out something important.
|
|
</p>
|
|
<span id="index-patches_002c-contributing"></span>
|
|
<p>Patches are welcome; if possible, please make them with ‘<samp>diff <span class="nolinebreak">-c</span><!-- /@w --></samp>’ (see <a data-manual="diff" href="diff.html#Top">Overview</a> in <cite>Comparing and Merging Files</cite>) and
|
|
include <samp>ChangeLog</samp> entries (see <a data-manual="emacs" href="https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Change-Log">Change Log</a> in <cite>The GNU
|
|
Emacs Manual</cite>). Please follow the existing coding style.
|
|
</p>
|
|
|
|
<hr>
|
|
</div>
|
|
<div class="appendix" id="GNU-Free-Documentation-License">
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="#Concept-index" accesskey="n" rel="next">Concept index</a>, Previous: <a href="#Reporting-bugs" accesskey="p" rel="prev">Reporting bugs</a>, Up: <a href="#Top" accesskey="u" rel="up">Time</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<span id="GNU-Free-Documentation-License-1"></span><h2 class="appendix">Appendix A GNU Free Documentation License</h2>
|
|
|
|
<div align="center">Version 1.3, 3 November 2008
|
|
</div>
|
|
|
|
<div class="display">
|
|
<pre class="display">Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
|
|
<a href="https://fsf.org/">https://fsf.org/</a>
|
|
|
|
Everyone is permitted to copy and distribute verbatim copies
|
|
of this license document, but changing it is not allowed.
|
|
</pre></div>
|
|
|
|
<ol start="0">
|
|
<li> PREAMBLE
|
|
|
|
<p>The purpose of this License is to make a manual, textbook, or other
|
|
functional and useful document <em>free</em> in the sense of freedom: to
|
|
assure everyone the effective freedom to copy and redistribute it,
|
|
with or without modifying it, either commercially or noncommercially.
|
|
Secondarily, this License preserves for the author and publisher a way
|
|
to get credit for their work, while not being considered responsible
|
|
for modifications made by others.
|
|
</p>
|
|
<p>This License is a kind of “copyleft”, which means that derivative
|
|
works of the document must themselves be free in the same sense. It
|
|
complements the GNU General Public License, which is a copyleft
|
|
license designed for free software.
|
|
</p>
|
|
<p>We have designed this License in order to use it for manuals for free
|
|
software, because free software needs free documentation: a free
|
|
program should come with manuals providing the same freedoms that the
|
|
software does. But this License is not limited to software manuals;
|
|
it can be used for any textual work, regardless of subject matter or
|
|
whether it is published as a printed book. We recommend this License
|
|
principally for works whose purpose is instruction or reference.
|
|
</p>
|
|
</li><li> APPLICABILITY AND DEFINITIONS
|
|
|
|
<p>This License applies to any manual or other work, in any medium, that
|
|
contains a notice placed by the copyright holder saying it can be
|
|
distributed under the terms of this License. Such a notice grants a
|
|
world-wide, royalty-free license, unlimited in duration, to use that
|
|
work under the conditions stated herein. The “Document”, below,
|
|
refers to any such manual or work. Any member of the public is a
|
|
licensee, and is addressed as “you”. You accept the license if you
|
|
copy, modify or distribute the work in a way requiring permission
|
|
under copyright law.
|
|
</p>
|
|
<p>A “Modified Version” of the Document means any work containing the
|
|
Document or a portion of it, either copied verbatim, or with
|
|
modifications and/or translated into another language.
|
|
</p>
|
|
<p>A “Secondary Section” is a named appendix or a front-matter section
|
|
of the Document that deals exclusively with the relationship of the
|
|
publishers or authors of the Document to the Document’s overall
|
|
subject (or to related matters) and contains nothing that could fall
|
|
directly within that overall subject. (Thus, if the Document is in
|
|
part a textbook of mathematics, a Secondary Section may not explain
|
|
any mathematics.) The relationship could be a matter of historical
|
|
connection with the subject or with related matters, or of legal,
|
|
commercial, philosophical, ethical or political position regarding
|
|
them.
|
|
</p>
|
|
<p>The “Invariant Sections” are certain Secondary Sections whose titles
|
|
are designated, as being those of Invariant Sections, in the notice
|
|
that says that the Document is released under this License. If a
|
|
section does not fit the above definition of Secondary then it is not
|
|
allowed to be designated as Invariant. The Document may contain zero
|
|
Invariant Sections. If the Document does not identify any Invariant
|
|
Sections then there are none.
|
|
</p>
|
|
<p>The “Cover Texts” are certain short passages of text that are listed,
|
|
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
|
|
the Document is released under this License. A Front-Cover Text may
|
|
be at most 5 words, and a Back-Cover Text may be at most 25 words.
|
|
</p>
|
|
<p>A “Transparent” copy of the Document means a machine-readable copy,
|
|
represented in a format whose specification is available to the
|
|
general public, that is suitable for revising the document
|
|
straightforwardly with generic text editors or (for images composed of
|
|
pixels) generic paint programs or (for drawings) some widely available
|
|
drawing editor, and that is suitable for input to text formatters or
|
|
for automatic translation to a variety of formats suitable for input
|
|
to text formatters. A copy made in an otherwise Transparent file
|
|
format whose markup, or absence of markup, has been arranged to thwart
|
|
or discourage subsequent modification by readers is not Transparent.
|
|
An image format is not Transparent if used for any substantial amount
|
|
of text. A copy that is not “Transparent” is called “Opaque”.
|
|
</p>
|
|
<p>Examples of suitable formats for Transparent copies include plain
|
|
ASCII without markup, Texinfo input format, LaTeX input
|
|
format, SGML or XML using a publicly available
|
|
DTD, and standard-conforming simple HTML,
|
|
PostScript or PDF designed for human modification. Examples
|
|
of transparent image formats include PNG, XCF and
|
|
JPG. Opaque formats include proprietary formats that can be
|
|
read and edited only by proprietary word processors, SGML or
|
|
XML for which the DTD and/or processing tools are
|
|
not generally available, and the machine-generated HTML,
|
|
PostScript or PDF produced by some word processors for
|
|
output purposes only.
|
|
</p>
|
|
<p>The “Title Page” means, for a printed book, the title page itself,
|
|
plus such following pages as are needed to hold, legibly, the material
|
|
this License requires to appear in the title page. For works in
|
|
formats which do not have any title page as such, “Title Page” means
|
|
the text near the most prominent appearance of the work’s title,
|
|
preceding the beginning of the body of the text.
|
|
</p>
|
|
<p>The “publisher” means any person or entity that distributes copies
|
|
of the Document to the public.
|
|
</p>
|
|
<p>A section “Entitled XYZ” means a named subunit of the Document whose
|
|
title either is precisely XYZ or contains XYZ in parentheses following
|
|
text that translates XYZ in another language. (Here XYZ stands for a
|
|
specific section name mentioned below, such as “Acknowledgements”,
|
|
“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title”
|
|
of such a section when you modify the Document means that it remains a
|
|
section “Entitled XYZ” according to this definition.
|
|
</p>
|
|
<p>The Document may include Warranty Disclaimers next to the notice which
|
|
states that this License applies to the Document. These Warranty
|
|
Disclaimers are considered to be included by reference in this
|
|
License, but only as regards disclaiming warranties: any other
|
|
implication that these Warranty Disclaimers may have is void and has
|
|
no effect on the meaning of this License.
|
|
</p>
|
|
</li><li> VERBATIM COPYING
|
|
|
|
<p>You may copy and distribute the Document in any medium, either
|
|
commercially or noncommercially, provided that this License, the
|
|
copyright notices, and the license notice saying this License applies
|
|
to the Document are reproduced in all copies, and that you add no other
|
|
conditions whatsoever to those of this License. You may not use
|
|
technical measures to obstruct or control the reading or further
|
|
copying of the copies you make or distribute. However, you may accept
|
|
compensation in exchange for copies. If you distribute a large enough
|
|
number of copies you must also follow the conditions in section 3.
|
|
</p>
|
|
<p>You may also lend copies, under the same conditions stated above, and
|
|
you may publicly display copies.
|
|
</p>
|
|
</li><li> COPYING IN QUANTITY
|
|
|
|
<p>If you publish printed copies (or copies in media that commonly have
|
|
printed covers) of the Document, numbering more than 100, and the
|
|
Document’s license notice requires Cover Texts, you must enclose the
|
|
copies in covers that carry, clearly and legibly, all these Cover
|
|
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
|
|
the back cover. Both covers must also clearly and legibly identify
|
|
you as the publisher of these copies. The front cover must present
|
|
the full title with all words of the title equally prominent and
|
|
visible. You may add other material on the covers in addition.
|
|
Copying with changes limited to the covers, as long as they preserve
|
|
the title of the Document and satisfy these conditions, can be treated
|
|
as verbatim copying in other respects.
|
|
</p>
|
|
<p>If the required texts for either cover are too voluminous to fit
|
|
legibly, you should put the first ones listed (as many as fit
|
|
reasonably) on the actual cover, and continue the rest onto adjacent
|
|
pages.
|
|
</p>
|
|
<p>If you publish or distribute Opaque copies of the Document numbering
|
|
more than 100, you must either include a machine-readable Transparent
|
|
copy along with each Opaque copy, or state in or with each Opaque copy
|
|
a computer-network location from which the general network-using
|
|
public has access to download using public-standard network protocols
|
|
a complete Transparent copy of the Document, free of added material.
|
|
If you use the latter option, you must take reasonably prudent steps,
|
|
when you begin distribution of Opaque copies in quantity, to ensure
|
|
that this Transparent copy will remain thus accessible at the stated
|
|
location until at least one year after the last time you distribute an
|
|
Opaque copy (directly or through your agents or retailers) of that
|
|
edition to the public.
|
|
</p>
|
|
<p>It is requested, but not required, that you contact the authors of the
|
|
Document well before redistributing any large number of copies, to give
|
|
them a chance to provide you with an updated version of the Document.
|
|
</p>
|
|
</li><li> MODIFICATIONS
|
|
|
|
<p>You may copy and distribute a Modified Version of the Document under
|
|
the conditions of sections 2 and 3 above, provided that you release
|
|
the Modified Version under precisely this License, with the Modified
|
|
Version filling the role of the Document, thus licensing distribution
|
|
and modification of the Modified Version to whoever possesses a copy
|
|
of it. In addition, you must do these things in the Modified Version:
|
|
</p>
|
|
<ol type="A" start="1">
|
|
<li> Use in the Title Page (and on the covers, if any) a title distinct
|
|
from that of the Document, and from those of previous versions
|
|
(which should, if there were any, be listed in the History section
|
|
of the Document). You may use the same title as a previous version
|
|
if the original publisher of that version gives permission.
|
|
|
|
</li><li> List on the Title Page, as authors, one or more persons or entities
|
|
responsible for authorship of the modifications in the Modified
|
|
Version, together with at least five of the principal authors of the
|
|
Document (all of its principal authors, if it has fewer than five),
|
|
unless they release you from this requirement.
|
|
|
|
</li><li> State on the Title page the name of the publisher of the
|
|
Modified Version, as the publisher.
|
|
|
|
</li><li> Preserve all the copyright notices of the Document.
|
|
|
|
</li><li> Add an appropriate copyright notice for your modifications
|
|
adjacent to the other copyright notices.
|
|
|
|
</li><li> Include, immediately after the copyright notices, a license notice
|
|
giving the public permission to use the Modified Version under the
|
|
terms of this License, in the form shown in the Addendum below.
|
|
|
|
</li><li> Preserve in that license notice the full lists of Invariant Sections
|
|
and required Cover Texts given in the Document’s license notice.
|
|
|
|
</li><li> Include an unaltered copy of this License.
|
|
|
|
</li><li> Preserve the section Entitled “History”, Preserve its Title, and add
|
|
to it an item stating at least the title, year, new authors, and
|
|
publisher of the Modified Version as given on the Title Page. If
|
|
there is no section Entitled “History” in the Document, create one
|
|
stating the title, year, authors, and publisher of the Document as
|
|
given on its Title Page, then add an item describing the Modified
|
|
Version as stated in the previous sentence.
|
|
|
|
</li><li> Preserve the network location, if any, given in the Document for
|
|
public access to a Transparent copy of the Document, and likewise
|
|
the network locations given in the Document for previous versions
|
|
it was based on. These may be placed in the “History” section.
|
|
You may omit a network location for a work that was published at
|
|
least four years before the Document itself, or if the original
|
|
publisher of the version it refers to gives permission.
|
|
|
|
</li><li> For any section Entitled “Acknowledgements” or “Dedications”, Preserve
|
|
the Title of the section, and preserve in the section all the
|
|
substance and tone of each of the contributor acknowledgements and/or
|
|
dedications given therein.
|
|
|
|
</li><li> Preserve all the Invariant Sections of the Document,
|
|
unaltered in their text and in their titles. Section numbers
|
|
or the equivalent are not considered part of the section titles.
|
|
|
|
</li><li> Delete any section Entitled “Endorsements”. Such a section
|
|
may not be included in the Modified Version.
|
|
|
|
</li><li> Do not retitle any existing section to be Entitled “Endorsements” or
|
|
to conflict in title with any Invariant Section.
|
|
|
|
</li><li> Preserve any Warranty Disclaimers.
|
|
</li></ol>
|
|
|
|
<p>If the Modified Version includes new front-matter sections or
|
|
appendices that qualify as Secondary Sections and contain no material
|
|
copied from the Document, you may at your option designate some or all
|
|
of these sections as invariant. To do this, add their titles to the
|
|
list of Invariant Sections in the Modified Version’s license notice.
|
|
These titles must be distinct from any other section titles.
|
|
</p>
|
|
<p>You may add a section Entitled “Endorsements”, provided it contains
|
|
nothing but endorsements of your Modified Version by various
|
|
parties—for example, statements of peer review or that the text has
|
|
been approved by an organization as the authoritative definition of a
|
|
standard.
|
|
</p>
|
|
<p>You may add a passage of up to five words as a Front-Cover Text, and a
|
|
passage of up to 25 words as a Back-Cover Text, to the end of the list
|
|
of Cover Texts in the Modified Version. Only one passage of
|
|
Front-Cover Text and one of Back-Cover Text may be added by (or
|
|
through arrangements made by) any one entity. If the Document already
|
|
includes a cover text for the same cover, previously added by you or
|
|
by arrangement made by the same entity you are acting on behalf of,
|
|
you may not add another; but you may replace the old one, on explicit
|
|
permission from the previous publisher that added the old one.
|
|
</p>
|
|
<p>The author(s) and publisher(s) of the Document do not by this License
|
|
give permission to use their names for publicity for or to assert or
|
|
imply endorsement of any Modified Version.
|
|
</p>
|
|
</li><li> COMBINING DOCUMENTS
|
|
|
|
<p>You may combine the Document with other documents released under this
|
|
License, under the terms defined in section 4 above for modified
|
|
versions, provided that you include in the combination all of the
|
|
Invariant Sections of all of the original documents, unmodified, and
|
|
list them all as Invariant Sections of your combined work in its
|
|
license notice, and that you preserve all their Warranty Disclaimers.
|
|
</p>
|
|
<p>The combined work need only contain one copy of this License, and
|
|
multiple identical Invariant Sections may be replaced with a single
|
|
copy. If there are multiple Invariant Sections with the same name but
|
|
different contents, make the title of each such section unique by
|
|
adding at the end of it, in parentheses, the name of the original
|
|
author or publisher of that section if known, or else a unique number.
|
|
Make the same adjustment to the section titles in the list of
|
|
Invariant Sections in the license notice of the combined work.
|
|
</p>
|
|
<p>In the combination, you must combine any sections Entitled “History”
|
|
in the various original documents, forming one section Entitled
|
|
“History”; likewise combine any sections Entitled “Acknowledgements”,
|
|
and any sections Entitled “Dedications”. You must delete all
|
|
sections Entitled “Endorsements.”
|
|
</p>
|
|
</li><li> COLLECTIONS OF DOCUMENTS
|
|
|
|
<p>You may make a collection consisting of the Document and other documents
|
|
released under this License, and replace the individual copies of this
|
|
License in the various documents with a single copy that is included in
|
|
the collection, provided that you follow the rules of this License for
|
|
verbatim copying of each of the documents in all other respects.
|
|
</p>
|
|
<p>You may extract a single document from such a collection, and distribute
|
|
it individually under this License, provided you insert a copy of this
|
|
License into the extracted document, and follow this License in all
|
|
other respects regarding verbatim copying of that document.
|
|
</p>
|
|
</li><li> AGGREGATION WITH INDEPENDENT WORKS
|
|
|
|
<p>A compilation of the Document or its derivatives with other separate
|
|
and independent documents or works, in or on a volume of a storage or
|
|
distribution medium, is called an “aggregate” if the copyright
|
|
resulting from the compilation is not used to limit the legal rights
|
|
of the compilation’s users beyond what the individual works permit.
|
|
When the Document is included in an aggregate, this License does not
|
|
apply to the other works in the aggregate which are not themselves
|
|
derivative works of the Document.
|
|
</p>
|
|
<p>If the Cover Text requirement of section 3 is applicable to these
|
|
copies of the Document, then if the Document is less than one half of
|
|
the entire aggregate, the Document’s Cover Texts may be placed on
|
|
covers that bracket the Document within the aggregate, or the
|
|
electronic equivalent of covers if the Document is in electronic form.
|
|
Otherwise they must appear on printed covers that bracket the whole
|
|
aggregate.
|
|
</p>
|
|
</li><li> TRANSLATION
|
|
|
|
<p>Translation is considered a kind of modification, so you may
|
|
distribute translations of the Document under the terms of section 4.
|
|
Replacing Invariant Sections with translations requires special
|
|
permission from their copyright holders, but you may include
|
|
translations of some or all Invariant Sections in addition to the
|
|
original versions of these Invariant Sections. You may include a
|
|
translation of this License, and all the license notices in the
|
|
Document, and any Warranty Disclaimers, provided that you also include
|
|
the original English version of this License and the original versions
|
|
of those notices and disclaimers. In case of a disagreement between
|
|
the translation and the original version of this License or a notice
|
|
or disclaimer, the original version will prevail.
|
|
</p>
|
|
<p>If a section in the Document is Entitled “Acknowledgements”,
|
|
“Dedications”, or “History”, the requirement (section 4) to Preserve
|
|
its Title (section 1) will typically require changing the actual
|
|
title.
|
|
</p>
|
|
</li><li> TERMINATION
|
|
|
|
<p>You may not copy, modify, sublicense, or distribute the Document
|
|
except as expressly provided under this License. Any attempt
|
|
otherwise to copy, modify, sublicense, or distribute it is void, and
|
|
will automatically terminate your rights under this License.
|
|
</p>
|
|
<p>However, if you cease all violation of this License, then your license
|
|
from a particular copyright holder is reinstated (a) provisionally,
|
|
unless and until the copyright holder explicitly and finally
|
|
terminates your license, and (b) permanently, if the copyright holder
|
|
fails to notify you of the violation by some reasonable means prior to
|
|
60 days after the cessation.
|
|
</p>
|
|
<p>Moreover, your license from a particular copyright holder is
|
|
reinstated permanently if the copyright holder notifies you of the
|
|
violation by some reasonable means, this is the first time you have
|
|
received notice of violation of this License (for any work) from that
|
|
copyright holder, and you cure the violation prior to 30 days after
|
|
your receipt of the notice.
|
|
</p>
|
|
<p>Termination of your rights under this section does not terminate the
|
|
licenses of parties who have received copies or rights from you under
|
|
this License. If your rights have been terminated and not permanently
|
|
reinstated, receipt of a copy of some or all of the same material does
|
|
not give you any rights to use it.
|
|
</p>
|
|
</li><li> FUTURE REVISIONS OF THIS LICENSE
|
|
|
|
<p>The Free Software Foundation may publish new, revised versions
|
|
of the GNU Free Documentation License from time to time. Such new
|
|
versions will be similar in spirit to the present version, but may
|
|
differ in detail to address new problems or concerns. See
|
|
<a href="https://www.gnu.org/copyleft/">https://www.gnu.org/copyleft/</a>.
|
|
</p>
|
|
<p>Each version of the License is given a distinguishing version number.
|
|
If the Document specifies that a particular numbered version of this
|
|
License “or any later version” applies to it, you have the option of
|
|
following the terms and conditions either of that specified version or
|
|
of any later version that has been published (not as a draft) by the
|
|
Free Software Foundation. If the Document does not specify a version
|
|
number of this License, you may choose any version ever published (not
|
|
as a draft) by the Free Software Foundation. If the Document
|
|
specifies that a proxy can decide which future versions of this
|
|
License can be used, that proxy’s public statement of acceptance of a
|
|
version permanently authorizes you to choose that version for the
|
|
Document.
|
|
</p>
|
|
</li><li> RELICENSING
|
|
|
|
<p>“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
|
|
World Wide Web server that publishes copyrightable works and also
|
|
provides prominent facilities for anybody to edit those works. A
|
|
public wiki that anybody can edit is an example of such a server. A
|
|
“Massive Multiauthor Collaboration” (or “MMC”) contained in the
|
|
site means any set of copyrightable works thus published on the MMC
|
|
site.
|
|
</p>
|
|
<p>“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
|
|
license published by Creative Commons Corporation, a not-for-profit
|
|
corporation with a principal place of business in San Francisco,
|
|
California, as well as future copyleft versions of that license
|
|
published by that same organization.
|
|
</p>
|
|
<p>“Incorporate” means to publish or republish a Document, in whole or
|
|
in part, as part of another Document.
|
|
</p>
|
|
<p>An MMC is “eligible for relicensing” if it is licensed under this
|
|
License, and if all works that were first published under this License
|
|
somewhere other than this MMC, and subsequently incorporated in whole
|
|
or in part into the MMC, (1) had no cover texts or invariant sections,
|
|
and (2) were thus incorporated prior to November 1, 2008.
|
|
</p>
|
|
<p>The operator of an MMC Site may republish an MMC contained in the site
|
|
under CC-BY-SA on the same site at any time before August 1, 2009,
|
|
provided the MMC is eligible for relicensing.
|
|
</p>
|
|
</li></ol>
|
|
|
|
<span id="ADDENDUM_003a-How-to-use-this-License-for-your-documents"></span><h3 class="heading">ADDENDUM: How to use this License for your documents</h3>
|
|
|
|
<p>To use this License in a document you have written, include a copy of
|
|
the License in the document and put the following copyright and
|
|
license notices just after the title page:
|
|
</p>
|
|
<div class="example">
|
|
<pre class="example"> Copyright (C) <var>year</var> <var>your name</var>.
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3
|
|
or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
|
Texts. A copy of the license is included in the section entitled ``GNU
|
|
Free Documentation License''.
|
|
</pre></div>
|
|
|
|
<p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
|
|
replace the “with…Texts.” line with this:
|
|
</p>
|
|
<div class="example">
|
|
<pre class="example"> with the Invariant Sections being <var>list their titles</var>, with
|
|
the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts
|
|
being <var>list</var>.
|
|
</pre></div>
|
|
|
|
<p>If you have Invariant Sections without Cover Texts, or some other
|
|
combination of the three, merge those two alternatives to suit the
|
|
situation.
|
|
</p>
|
|
<p>If your document contains nontrivial examples of program code, we
|
|
recommend releasing these examples in parallel under your choice of
|
|
free software license, such as the GNU General Public License,
|
|
to permit their use in free software.
|
|
</p>
|
|
|
|
|
|
<hr>
|
|
</div>
|
|
<div class="unnumbered" id="Concept-index">
|
|
<div class="header">
|
|
<p>
|
|
Previous: <a href="#GNU-Free-Documentation-License" accesskey="p" rel="prev">GNU Free Documentation License</a>, Up: <a href="#Top" accesskey="u" rel="up">Time</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<span id="Concept-index-1"></span><h2 class="unnumbered">Concept index</h2>
|
|
|
|
<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Concept-index_cp_letter-B"><b>B</b></a>
|
|
|
|
<a class="summary-letter" href="#Concept-index_cp_letter-C"><b>C</b></a>
|
|
|
|
<a class="summary-letter" href="#Concept-index_cp_letter-F"><b>F</b></a>
|
|
|
|
<a class="summary-letter" href="#Concept-index_cp_letter-P"><b>P</b></a>
|
|
|
|
<a class="summary-letter" href="#Concept-index_cp_letter-R"><b>R</b></a>
|
|
|
|
<a class="summary-letter" href="#Concept-index_cp_letter-V"><b>V</b></a>
|
|
|
|
</td></tr></table>
|
|
<table class="index-cp" border="0">
|
|
<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr>
|
|
<tr><td colspan="4"> <hr></td></tr>
|
|
<tr><th id="Concept-index_cp_letter-B">B</th><td></td><td></td></tr>
|
|
<tr><td></td><td valign="top"><a href="#index-bug-reporting">bug reporting</a>:</td><td> </td><td valign="top"><a href="#Reporting-bugs">Reporting bugs</a></td></tr>
|
|
<tr><td colspan="4"> <hr></td></tr>
|
|
<tr><th id="Concept-index_cp_letter-C">C</th><td></td><td></td></tr>
|
|
<tr><td></td><td valign="top"><a href="#index-checklist-for-bug-reports">checklist for bug reports</a>:</td><td> </td><td valign="top"><a href="#Reporting-bugs">Reporting bugs</a></td></tr>
|
|
<tr><td colspan="4"> <hr></td></tr>
|
|
<tr><th id="Concept-index_cp_letter-F">F</th><td></td><td></td></tr>
|
|
<tr><td></td><td valign="top"><a href="#index-format">format</a>:</td><td> </td><td valign="top"><a href="#Setting-Format">Setting Format</a></td></tr>
|
|
<tr><td></td><td valign="top"><a href="#index-format-1">format</a>:</td><td> </td><td valign="top"><a href="#Format-String">Format String</a></td></tr>
|
|
<tr><td></td><td valign="top"><a href="#index-format-2">format</a>:</td><td> </td><td valign="top"><a href="#Invoking-time">Invoking time</a></td></tr>
|
|
<tr><td colspan="4"> <hr></td></tr>
|
|
<tr><th id="Concept-index_cp_letter-P">P</th><td></td><td></td></tr>
|
|
<tr><td></td><td valign="top"><a href="#index-patches_002c-contributing">patches, contributing</a>:</td><td> </td><td valign="top"><a href="#Reporting-bugs">Reporting bugs</a></td></tr>
|
|
<tr><td></td><td valign="top"><a href="#index-problems">problems</a>:</td><td> </td><td valign="top"><a href="#Reporting-bugs">Reporting bugs</a></td></tr>
|
|
<tr><td colspan="4"> <hr></td></tr>
|
|
<tr><th id="Concept-index_cp_letter-R">R</th><td></td><td></td></tr>
|
|
<tr><td></td><td valign="top"><a href="#index-reporting-bugs">reporting bugs</a>:</td><td> </td><td valign="top"><a href="#Reporting-bugs">Reporting bugs</a></td></tr>
|
|
<tr><td colspan="4"> <hr></td></tr>
|
|
<tr><th id="Concept-index_cp_letter-V">V</th><td></td><td></td></tr>
|
|
<tr><td></td><td valign="top"><a href="#index-version-number">version number</a>:</td><td> </td><td valign="top"><a href="#Invoking-time">Invoking time</a></td></tr>
|
|
<tr><td colspan="4"> <hr></td></tr>
|
|
</table>
|
|
<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Concept-index_cp_letter-B"><b>B</b></a>
|
|
|
|
<a class="summary-letter" href="#Concept-index_cp_letter-C"><b>C</b></a>
|
|
|
|
<a class="summary-letter" href="#Concept-index_cp_letter-F"><b>F</b></a>
|
|
|
|
<a class="summary-letter" href="#Concept-index_cp_letter-P"><b>P</b></a>
|
|
|
|
<a class="summary-letter" href="#Concept-index_cp_letter-R"><b>R</b></a>
|
|
|
|
<a class="summary-letter" href="#Concept-index_cp_letter-V"><b>V</b></a>
|
|
|
|
</td></tr></table>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|