1wrap_log_reader(3)         Erlang Module Definition         wrap_log_reader(3)
2
3
4

NAME

6       wrap_log_reader  -  A  service  to  read internally formatted wrap disk
7       logs.
8
9

DESCRIPTION

11       This module makes it possible to read internally  formatted  wrap  disk
12       logs, see disk_log(3). wrap_log_reader does not interfere with disk_log
13       activities;  there  is  however  a  bug  in   this   version   of   the
14       wrap_log_reader, see section Known Limitations.
15
16       A  wrap disk log file consists of many files, called index files. A log
17       file can be opened and closed. Also, a single index file can be  opened
18       separately.  If  a  non-existent  or  non-internally  formatted file is
19       opened, an error message is returned. If the file is  corrupt,  no  at‐
20       tempt is made to repair it, but an error message is returned.
21
22       If a log is configured to be distributed, it is possible that all items
23       are not logged on all nodes. wrap_log_reader only reads the log on  the
24       called node; it is up to the user to be sure that all items are read.
25

DATA TYPES

27       continuation()
28
29              Continuation returned by open/1,2 or chunk/1,2.
30

EXPORTS

32       chunk(Continuation) -> chunk_ret()
33
34       chunk(Continuation, N) -> chunk_ret()
35
36              Types:
37
38                 Continuation = continuation()
39                 N = infinity | integer() >= 1
40                 chunk_ret() =
41                     {Continuation2 :: term(), Terms :: [term()]} |
42                     {Continuation2 :: term(),
43                      Terms :: [term()],
44                      Badbytes :: integer() >= 0} |
45                     {Continuation2 :: term(), eof} |
46                     {error, Reason :: term()}
47
48              Enables  to  efficiently  read  the terms that are appended to a
49              log. Minimises disk I/O by reading 64 kilobyte chunks  from  the
50              file.
51
52              The  first  time  chunk() is called, an initial continuation re‐
53              turned from open/1 or open/2 must be provided.
54
55              When chunk/3 is called, N controls the maximum number  of  terms
56              that  are read from the log in each chunk. Defaults to infinity,
57              which means that all the terms contained in  the  8K  chunk  are
58              read. If less than N terms are returned, this does not necessar‐
59              ily mean that end of file is reached.
60
61              Returns a tuple {Continuation2, Terms}, where Terms is a list of
62              terms  found  in the log. Continuation2 is yet another continua‐
63              tion that must be passed on to any subsequent calls to  chunk().
64              With  a  series  of calls to chunk(), it is then possible to ex‐
65              tract all terms from a log.
66
67              Returns a tuple {Continuation2, Terms, Badbytes} if the  log  is
68              opened in read only mode and the read chunk is corrupt. Badbytes
69              indicates the number of non-Erlang terms found in the chunk. No‐
70              tice that the log is not repaired.
71
72              Returns {Continuation2, eof} when the end of the log is reached,
73              and {error, Reason} if an error occurs.
74
75              The returned continuation either is or is not valid in the  next
76              call  to  this  function.  This  is because the log can wrap and
77              delete the file into which the continuation  points.  To  ensure
78              this does not occur, the log can be blocked during the search.
79
80       close(Continuation) -> ok | {error, Reason}
81
82              Types:
83
84                 Continuation = continuation()
85                 Reason = file:posix()
86
87              Closes a log file properly.
88
89       open(Filename) -> open_ret()
90
91       open(Filename, N) -> open_ret()
92
93              Types:
94
95                 Filename = string() | atom()
96                 N = integer()
97                 open_ret() =
98                     {ok, Continuation :: continuation()} |
99                     {error, Reason :: tuple()}
100
101              Filename specifies the name of the file to be read.
102
103              N  specifies  the index of the file to be read. If N is omitted,
104              the whole wrap log file is read; if it is  specified,  only  the
105              specified index file is read.
106
107              Returns  {ok, Continuation} if the log/index file is opened suc‐
108              cessfully. Continuation is to be used when chunking  or  closing
109              the file.
110
111              Returns {error, Reason} for all errors.
112

KNOWN LIMITATIONS

114       This  version of wrap_log_reader does not detect if disk_log wraps to a
115       new index file between a call to wrap_log_reader:open() and  the  first
116       call  to  wrap_log_reader:chunk().  If this occurs, the call to chunk()
117       reads the last logged items in the log file, as the opened  index  file
118       was truncated by disk_log.
119

SEE ALSO

121       disk_log(3)
122
123
124
125Ericsson AB                       kernel 9.1                wrap_log_reader(3)
Impressum