Add wrbuf_sha1_puts

[yaz-moved-to-github.git] / doc / yaz-log-man.xml

diff --git a/doc/yaz-log-man.xml b/doc/yaz-log-man.xml
index 5f98ee4..abf9ccf 100644 (file)
--- a/doc/yaz-log-man.xml
+++ b/doc/yaz-log-man.xml
@@ -1,18 +1,31 @@
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
- "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
->
-<!-- $Id: yaz-log-man.xml,v 1.3 2006-04-24 12:41:00 marc Exp $ -->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
+[
+     <!ENTITY % local SYSTEM "local.ent">
+     %local;
+     <!ENTITY % entities SYSTEM "entities.ent">
+     %entities;
+     <!ENTITY % idcommon SYSTEM "common/common.ent">
+     %idcommon;
+]>

 <refentry id="yaz-log">
 <refentry id="yaz-log">

+ <refentryinfo>
+  <productname>YAZ</productname>
+  <productnumber>&version;</productnumber>
+  <info><orgname>Index Data</orgname></info>
+ </refentryinfo>
+

  <refmeta>
   <refentrytitle>yaz-log</refentrytitle>
   <manvolnum>7</manvolnum>
  <refmeta>
   <refentrytitle>yaz-log</refentrytitle>
   <manvolnum>7</manvolnum>

+  <refmiscinfo class="manual">Conventions and miscellaneous</refmiscinfo>

  </refmeta>
  </refmeta>

- 
+

  <refnamediv>
   <refname>yaz-log</refname>
   <refpurpose>Log handling in all yaz-based programs</refpurpose>
  </refnamediv>
  <refnamediv>
   <refname>yaz-log</refname>
   <refpurpose>Log handling in all yaz-based programs</refpurpose>
  </refnamediv>

- 
+

  <refsynopsisdiv>
   <cmdsynopsis>
    <command>yaz-XXXX</command>
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>yaz-XXXX</command>

@@ -20,7 +33,7 @@
    <arg choice="opt"><option>-l <replaceable>logfile</replaceable></option></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
    <arg choice="opt"><option>-l <replaceable>logfile</replaceable></option></arg>
   </cmdsynopsis>
  </refsynopsisdiv>

- 
+

  <refsect1><title>DESCRIPTION</title>
   <para>
    All YAZ-based programs use a common log subsystem, and should support
  <refsect1><title>DESCRIPTION</title>
   <para>
    All YAZ-based programs use a common log subsystem, and should support

@@ -30,20 +43,31 @@
   <para>
   </para>
  </refsect1>
   <para>
   </para>
  </refsect1>

- 
+

  <refsect1><title>OPTIONS</title>
  <refsect1><title>OPTIONS</title>

-  
+

   <variablelist>
    <varlistentry>
     <term>-l<replaceable> logfile</replaceable></term>
   <variablelist>
    <varlistentry>
     <term>-l<replaceable> logfile</replaceable></term>

-    <listitem><para>
+    <listitem>
+     <para>

       Specify the file where the log is to be written. If none is specified,
       <filename>stderr</filename> is used. The log is appended to this file.
       If the file grows overly large, it is silently rotated: It is renamed to
       Specify the file where the log is to be written. If none is specified,
       <filename>stderr</filename> is used. The log is appended to this file.
       If the file grows overly large, it is silently rotated: It is renamed to

-      <replaceable>logfile</replaceable>.1 (old such file is deleted), and a
+      <replaceable>logfile</replaceable>.1,
+      <replaceable>logfile</replaceable>.2, .., 9
+      (old such file is deleted), and a

       new file is opened. The limit defaults to 1GB, but can be set by the
       program.
       new file is opened. The limit defaults to 1GB, but can be set by the
       program.

-    </para></listitem>
+      The rotating limit can be specified with option <literal>-r</literal>
+      for the YAZ frontend server (yaz-ztest).
+     </para>
+     <para>
+      Rotation can also be implicitly enabled by using a filename
+      which gets changed for a given date, due to substitutions as
+      given by the strftime(3) function.
+     </para>
+    </listitem>

    </varlistentry>
 
    <varlistentry>
    </varlistentry>
 
    <varlistentry>

@@ -64,7 +88,7 @@
 
  <refsect1><title>LOG LEVELS TO CONTROL LOGGING</title>
   <para>
 
  <refsect1><title>LOG LEVELS TO CONTROL LOGGING</title>
   <para>

-   Some of the log levels control the way the log is written. 
+   Some of the log levels control the way the log is written.

   </para>
   <para>
    <literal>flush</literal> causes the log to be flushed after every write.
   </para>
   <para>
    <literal>flush</literal> causes the log to be flushed after every write.

@@ -78,8 +102,8 @@
    intended for automatic test scripts, which should produce predictable log
    files that are easy to compare.
   </para>
    intended for automatic test scripts, which should produce predictable log
    files that are easy to compare.
   </para>

-  
- </refsect1> 
+
+ </refsect1>

 
  <refsect1><title>GENERAL LOG LEVELS IN YAZ ITSELF</title>
   <para>
 
  <refsect1><title>GENERAL LOG LEVELS IN YAZ ITSELF</title>
   <para>

@@ -99,7 +123,7 @@
    levels (see below).
   </para>
   <para>
    levels (see below).
   </para>
   <para>

-   <literal>all</literal> turns on almost all hard-coded log levels. 
+   <literal>all</literal> turns on almost all hard-coded log levels.

   </para>
   <para>
    <literal>loglevel</literal> logs information about the log levels used by
   </para>
   <para>
    <literal>loglevel</literal> logs information about the log levels used by

@@ -111,28 +135,28 @@
    is to grep for <function>yaz_log_module_level</function> in the source
    code, as in
    <screen>
    is to grep for <function>yaz_log_module_level</function> in the source
    code, as in
    <screen>

-      find . -name '*.[ch]' -print | 
-         xargs grep yaz_log_module_level | 
+      find . -name '*.[ch]' -print |
+         xargs grep yaz_log_module_level |

          grep '"' |
          grep '"' |

-         cut -d'"' -f2 | 
-         sort -u   
+         cut -d'"' -f2 |
+         sort -u

    </screen>
   </para>
   <para>
    </screen>
   </para>
   <para>

-   <literal>eventl</literal>, <literal>malloc</literal>, 
+   <literal>eventl</literal>, <literal>malloc</literal>,

    <literal>nmem</literal>, <literal>odr</literal> are used internally for
    debugging yaz.
   </para>
   <para>
   </para>
    <literal>nmem</literal>, <literal>odr</literal> are used internally for
    debugging yaz.
   </para>
   <para>
   </para>

- </refsect1> 
+ </refsect1>

 
  <refsect1><title>LOG LEVELS FOR CLIENTS</title>
   <para>
    <literal>zoom</literal> logs the calls to the zoom API, which may be useful
    in debugging client applications.
   </para>
 
  <refsect1><title>LOG LEVELS FOR CLIENTS</title>
   <para>
    <literal>zoom</literal> logs the calls to the zoom API, which may be useful
    in debugging client applications.
   </para>

- </refsect1> 
+ </refsect1>

 
  <refsect1><title>LOG LEVELS FOR SERVERS</title>
   <para>
 
  <refsect1><title>LOG LEVELS FOR SERVERS</title>
   <para>

@@ -155,9 +179,9 @@
    in addition to these. As they depend on the server in question, they can
    not be described here. See above how to find out about them.
   </para>
    in addition to these. As they depend on the server in question, they can
    not be described here. See above how to find out about them.
   </para>

- </refsect1> 
+ </refsect1>

 
 

- <refsect1><title>EXAMPLES</title>
+ <refsect1><title>LOGGING EXAMPLES</title>

   <para>
    See what log levels yaz-ztest is using:
    <screen>
   <para>
    See what log levels yaz-ztest is using:
    <screen>

@@ -207,9 +231,22 @@
    14:45:41-23/11 yaz-ztest [requestdetail] Request to pack 1+1 1
    14:45:41-23/11 yaz-ztest [requestdetail] pms=1048576, mrs=1048576
    14:45:41-23/11 yaz-ztest [request] Present: [1] 1+1  OK 1 records returned
    14:45:41-23/11 yaz-ztest [requestdetail] Request to pack 1+1 1
    14:45:41-23/11 yaz-ztest [requestdetail] pms=1048576, mrs=1048576
    14:45:41-23/11 yaz-ztest [request] Present: [1] 1+1  OK 1 records returned

-   </screen> 
+   </screen>
+  </para>
+ </refsect1>
+
+ <refsect1><title>LOG FILENAME EXAMPLES</title>
+  <para>
+   A file with format my_YYYYMMDD.log is where Y, M, D is year, month, and day
+   digits is given as follows
+   <literal>-l my_%Y%m%d.log</literal> . And since the filename
+   is depending on day, rotaion will occur on midnight.
+  </para>
+  <para>
+   A weekly log could be specified as
+   <literal>-l my_%Y%U.log</literal>.

   </para>
   </para>

- </refsect1> 
+ </refsect1>

 
  <refsect1><title>FILES</title>
   <para>
 
  <refsect1><title>FILES</title>
   <para>

@@ -219,15 +256,40 @@
  </refsect1>
  <refsect1><title>SEE ALSO</title>
   <para>
  </refsect1>
  <refsect1><title>SEE ALSO</title>
   <para>

-   yaz(7)
-   yaz-ztest(8) yaz-client(1) 
+   <citerefentry>
+    <refentrytitle>yaz</refentrytitle>
+    <manvolnum>7</manvolnum>
+   </citerefentry>
+
+   <citerefentry>
+    <refentrytitle>yaz-ztest</refentrytitle>
+    <manvolnum>8</manvolnum>
+   </citerefentry>
+
+   <citerefentry>
+    <refentrytitle>yaz-client</refentrytitle>
+    <manvolnum>1</manvolnum>
+   </citerefentry>
+
+   <citerefentry>
+    <refentrytitle>strftime</refentrytitle>
+    <manvolnum>3</manvolnum>
+   </citerefentry>

   </para>
  </refsect1>
 </refentry>
 
   </para>
  </refsect1>
 </refentry>
 

-<!-- Keep this Emacs mode comment at the end of the file
+<!-- Keep this comment at the end of the file

 Local variables:
 Local variables:

-mode: nxml
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-local-catalogs: nil
+sgml-namecase-general:t

 End:
 -->
 End:
 -->

-