<?xml version="1.0" encoding="latin1" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>1998</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> The contents of this file are subject to the Erlang Public License, Version 1.1, (the "License"); you may not use this file except in compliance with the License. You should have received a copy of the Erlang Public License along with this software. If not, it can be retrieved online at http://www.erlang.org/. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. </legalnotice> <title>wrap_log_reader</title> <prepared>Esko Vierumäki</prepared> <responsible>Esko Vierumäki</responsible> <docno></docno> <approved>nobody</approved> <checked>no</checked> <date>98-09-21</date> <rev>A</rev> <file>wrap_log_reader.sgml</file> </header> <module>wrap_log_reader</module> <modulesummary>A function to read internally formatted wrap disk logs</modulesummary> <description> <p><c>wrap_log_reader</c> is a function to read internally formatted wrap disk logs, refer to disk_log(3). <c>wrap_log_reader</c> does not interfere with disk_log activities; there is however a known bug in this version of the <c>wrap_log_reader</c>, see chapter <c>bugs</c> below. </p> <p>A wrap disk log file consists of several files, called index files. A log file can be opened and closed. It is also possible to open just one index file separately. If an non-existent or a non-internally formatted file is opened, an error message is returned. If the file is corrupt, no attempt to repair it will be done but an error message is returned. </p> <p>If a log is configured to be distributed, there is a possibility that all items are not loggen on all nodes. <c>wrap_log_reader</c> does only read the log on the called node, it is entirely up to the user to be sure that all items are read. </p> </description> <datatypes> <datatype> <name name="continuation"/> <desc><p>Continuation returned by <c>open/1,2</c> or <c>chunk/1,2</c>.</p> </desc> </datatype> </datatypes> <funcs> <func> <name name="chunk" arity="1"/> <name name="chunk" arity="2"/> <fsummary>Read a chunk of objects written to a wrap log.</fsummary> <type name="chunk_ret"/> <desc> <p>This function makes it possible to efficiently read the terms which have been appended to a log. It minimises disk I/O by reading large 8K chunks from the file. </p> <p>The first time <c>chunk</c> is called an initial continuation returned from the <c>open/1</c>, <c>open/2</c> must be provided. </p> <p>When <c>chunk/3</c> is called, <c><anno>N</anno></c> controls the maximum number of terms that are read from the log in each chunk. Default is <c>infinity</c>, which means that all the terms contained in the 8K chunk are read. If less than <c><anno>N</anno></c> terms are returned, this does not necessarily mean that end of file is reached. </p> <p>The <c>chunk</c> function returns a tuple <c>{<anno>Continuation2</anno>, <anno>Terms</anno>}</c>, where <c><anno>Terms</anno></c> is a list of terms found in the log. <c><anno>Continuation2</anno></c> is yet another continuation which must be passed on into any subsequent calls to <c>chunk</c>. With a series of calls to <c>chunk</c> it is then possible to extract all terms from a log. </p> <p>The <c>chunk</c> function returns a tuple <c>{<anno>Continuation2</anno>, <anno>Terms</anno>, <anno>Badbytes</anno>}</c> if the log is opened in read only mode and the read chunk is corrupt. <c><anno>Badbytes</anno></c> indicates the number of non-Erlang terms found in the chunk. Note also that the log is not repaired. </p> <p><c>chunk</c> returns <c>{<anno>Continuation2</anno>, eof}</c> when the end of the log is reached, and <c>{error, <anno>Reason</anno>}</c> if an error occurs. </p> <p>The returned continuation may or may not be valid in the next call to <c>chunk</c>. This is because the log may wrap and delete the file into which the continuation points. To make sure this does not happen, the log can be blocked during the search. </p> </desc> </func> <func> <name name="close" arity="1"/> <fsummary>Close a log</fsummary> <desc> <p>This function closes a log file properly. </p> </desc> </func> <func> <name name="open" arity="1"/> <name name="open" arity="2"/> <fsummary>Open a log file</fsummary> <type name="open_ret"/> <desc> <p><c><anno>Filename</anno></c> specifies the name of the file which is to be read. </p> <p><c><anno>N</anno></c> specifies the index of the file which is to be read. If <c><anno>N</anno></c> is omitted the whole wrap log file will be read; if it is specified only the specified index file will be read. </p> <p>The <c>open</c> function returns <c>{ok, <anno>Continuation</anno>}</c> if the log/index file was successfully opened. The <c><anno>Continuation</anno></c> is to be used when chunking or closing the file. </p> <p>The function returns <c>{error, <anno>Reason</anno>}</c> for all errors. </p> </desc> </func> </funcs> <section> <title>Bugs</title> <p>This version of the <c>wrap_log_reader</c> does not detect if the <c>disk_log</c> wraps to a new index file between a <c>wrap_log_reader:open</c> and the first <c>wrap_log_reader:chunk</c>. In this case the chuck will actually read the last logged items in the log file, because the opened index file was truncated by the <c>disk_log</c>. </p> </section> <section> <title>See Also</title> <p><seealso marker="disk_log">disk_log(3)</seealso></p> </section> </erlref>