NAME

       wrap_log_reader - A function to read internally formatted wrap disk logs

DESCRIPTION

       wrap_log_reader  is  a  function  to  read  internally formatted wrap disk logs, refer to disk_log(3erl).
       wrap_log_reader does not interfere with disk_log activities; there is however a known bug in this version
       of the wrap_log_reader, see chapter bugs below.

       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.

       If  a  log  is  configured to be distributed, there is a possibility that all items are not loggen on all
       nodes. wrap_log_reader does only read the log on the called node, it is entirely up to  the  user  to  be
       sure that all items are read.

DATA TYPES

       continuation()

              Continuation returned by open/1,2 or chunk/1,2.

EXPORTS

       chunk(Continuation) -> chunk_ret()

       chunk(Continuation, N) -> chunk_ret()

              Types:

                 Continuation = continuation()
                 N = infinity | integer() >= 1
                 chunk_ret() =
                     {Continuation2, Terms :: [term()]} |
                     {Continuation2,
                      Terms :: [term()],
                      Badbytes :: integer() >= 0} |
                     {Continuation2, eof} |
                     {error, Reason :: term()}

              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.

              The first time chunk is called an initial continuation returned from the open/1,  open/2  must  be
              provided.

              When  chunk/3 is called, N controls the maximum number of terms that are read from the log in each
              chunk. Default is infinity, which means that all the terms contained in the 8K chunk are read.  If
              less than N terms are returned, this does not necessarily mean that end of file is reached.

              The chunk function returns a tuple {Continuation2, Terms}, where Terms is a list of terms found in
              the  log.  Continuation2  is  yet another continuation which must be passed on into any subsequent
              calls to chunk. With a series of calls to chunk it is then possible to extract all  terms  from  a
              log.

              The  chunk  function returns a tuple {Continuation2, Terms, Badbytes} if the log is opened in read
              only mode and the read chunk is corrupt. Badbytes indicates the number of non-Erlang  terms  found
              in the chunk. Note also that the log is not repaired.

              chunk  returns  {Continuation2, eof} when the end of the log is reached, and {error, Reason} if an
              error occurs.

              The returned continuation may or may not be valid in the next call to chunk. 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.

       close(Continuation) -> ok | {error, Reason}

              Types:

                 Continuation = continuation()
                 Reason = file:posix()

              This function closes a log file properly.

       open(Filename) -> open_ret()

       open(Filename, N) -> open_ret()

              Types:

                 Filename = string() | atom()
                 N = integer()
                 open_ret() =
                     {ok, Continuation :: continuation()} |
                     {error, Reason :: tuple()}

              Filename specifies the name of the file which is to be read.

              N specifies the index of the file which is to be read. If N is omitted the  whole  wrap  log  file
              will be read; if it is specified only the specified index file will be read.

              The  open  function  returns {ok, Continuation} if the log/index file was successfully opened. The
              Continuation is to be used when chunking or closing the file.

              The function returns {error, Reason} for all errors.

BUGS

       This version of the wrap_log_reader does not detect if the disk_log wraps to a new index file  between  a
       wrap_log_reader:open  and  the first wrap_log_reader:chunk. 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 disk_log.

SEE ALSO

       disk_log(3erl)

Ericsson AB                                        kernel 4.2                              wrap_log_reader(3erl)