.TH wrap_log_reader 3erl "kernel 5.1.1" "Ericsson AB" "Erlang Module Definition"
.SH NAME
wrap_log_reader \- A service to read internally formatted wrap disk logs.
  
.SH DESCRIPTION
.LP
This module makes it possible to read internally formatted wrap disk logs, see \fB\fIdisk_log(3erl)\fR\&\fR\&\&. \fIwrap_log_reader\fR\& does not interfere with \fIdisk_log\fR\& activities; there is however a bug in this version of the \fIwrap_log_reader\fR\&, see section \fBKnown Limitations\fR\&\&.
.LP
A wrap disk log file consists of many files, called index files\&. A log file can be opened and closed\&. Also, a single index file can be opened separately\&. If a non-existent or non-internally formatted file is opened, an error message is returned\&. If the file is corrupt, no attempt is made to repair it, but an error message is returned\&.
.LP
If a log is configured to be distributed, it is possible that all items are not logged on all nodes\&. \fIwrap_log_reader\fR\& only reads the log on the called node; it is up to the user to be sure that all items are read\&.
.SH DATA TYPES
.nf

\fBcontinuation()\fR\&
.br
.fi
.RS
.LP
Continuation returned by \fIopen/1,2\fR\& or \fIchunk/1,2\fR\&\&.
.RE

.SH EXPORTS
.LP
.nf

.B
chunk(Continuation) -> chunk_ret()
.br
.fi
.br
.nf

.B
chunk(Continuation, N) -> chunk_ret()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Continuation = \fBcontinuation()\fR\&
.br
N = infinity | integer() >= 1
.br
.nf
\fBchunk_ret()\fR\& = 
.br
    {Continuation2, Terms :: [term()]} |
.br
    {Continuation2,
.br
     Terms :: [term()],
.br
     Badbytes :: integer() >= 0} |
.br
    {Continuation2, eof} |
.br
    {error, Reason :: term()}
.fi
.br
.RE
.RE
.RS
.LP
Enables to efficiently read the terms that are appended to a log\&. Minimises disk I/O by reading 64 kilobyte chunks from the file\&.
.LP
The first time \fIchunk()\fR\& is called, an initial continuation returned from \fIopen/1\fR\& or \fIopen/2\fR\& must be provided\&.
.LP
When \fIchunk/3\fR\& is called, \fIN\fR\& controls the maximum number of terms that are read from the log in each chunk\&. Defaults to \fIinfinity\fR\&, which means that all the terms contained in the 8K chunk are read\&. If less than \fIN\fR\& terms are returned, this does not necessarily mean that end of file is reached\&.
.LP
Returns a tuple \fI{Continuation2, Terms}\fR\&, where \fITerms\fR\& is a list of terms found in the log\&. \fIContinuation2\fR\& is yet another continuation that must be passed on to any subsequent calls to \fIchunk()\fR\&\&. With a series of calls to \fIchunk()\fR\&, it is then possible to extract all terms from a log\&.
.LP
Returns a tuple \fI{Continuation2, Terms, Badbytes}\fR\& if the log is opened in read only mode and the read chunk is corrupt\&. \fIBadbytes\fR\& indicates the number of non-Erlang terms found in the chunk\&. Notice that the log is not repaired\&.
.LP
Returns \fI{Continuation2, eof}\fR\& when the end of the log is reached, and \fI{error, Reason}\fR\& if an error occurs\&.
.LP
The returned continuation either is or is not valid in the next call to this function\&. This is because the log can wrap and delete the file into which the continuation points\&. To ensure this does not occur, the log can be blocked during the search\&.
.RE

.LP
.nf

.B
close(Continuation) -> ok | {error, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Continuation = \fBcontinuation()\fR\&
.br
Reason = \fBfile:posix()\fR\&
.br
.RE
.RE
.RS
.LP
Closes a log file properly\&.
.RE

.LP
.nf

.B
open(Filename) -> open_ret()
.br
.fi
.br
.nf

.B
open(Filename, N) -> open_ret()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Filename = string() | atom()
.br
N = integer()
.br
.nf
\fBopen_ret()\fR\& = 
.br
    {ok, Continuation :: \fBcontinuation()\fR\&} |
.br
    {error, Reason :: tuple()}
.fi
.br
.RE
.RE
.RS
.LP
\fIFilename\fR\& specifies the name of the file to be read\&.
.LP
\fIN\fR\& specifies the index of the file to be read\&. If \fIN\fR\& is omitted, the whole wrap log file is read; if it is specified, only the specified index file is read\&.
.LP
Returns \fI{ok, Continuation}\fR\& if the log/index file is opened successfully\&. \fIContinuation\fR\& is to be used when chunking or closing the file\&.
.LP
Returns \fI{error, Reason}\fR\& for all errors\&.
.RE

.SH "KNOWN LIMITATIONS"

.LP
This version of \fIwrap_log_reader\fR\& does not detect if \fIdisk_log\fR\& wraps to a new index file between a call to \fIwrap_log_reader:open()\fR\& and the first call to \fIwrap_log_reader:chunk()\fR\&\&. If this occurs, the call to \fIchunk()\fR\& reads the last logged items in the log file, as the opened index file was truncated by \fIdisk_log\fR\&\&.
.SH "SEE ALSO"

.LP
\fB\fIdisk_log(3erl)\fR\&\fR\&