diff options
Diffstat (limited to 'lib/kernel/doc/src/disk_log.xml')
| -rw-r--r-- | lib/kernel/doc/src/disk_log.xml | 451 |
1 files changed, 197 insertions, 254 deletions
diff --git a/lib/kernel/doc/src/disk_log.xml b/lib/kernel/doc/src/disk_log.xml index 324d4264cf..9721907162 100644 --- a/lib/kernel/doc/src/disk_log.xml +++ b/lib/kernel/doc/src/disk_log.xml @@ -179,13 +179,48 @@ reopen the log simultaneously.</p> </note> </description> + <datatypes> + <datatype> + <name name="log"/> + </datatype> + <datatype> + <name name="dlog_size"/> + </datatype> + <datatype> + <name name="dlog_format"/> + </datatype> + <datatype> + <name name="dlog_head_opt"/> + </datatype> + <datatype> + <name name="dlog_byte"/> + </datatype> + <datatype> + <name name="dlog_mode"/> + </datatype> + <datatype> + <name name="dlog_type"/> + </datatype> + <datatype> + <name name="continuation"/> + <desc><p>Chunk continuation returned by + <c>chunk/2,3</c>, <c>bchunk/2,3</c>, or <c>chunk_step/3</c>.</p> + </desc> + </datatype> + <datatype> + <name name="bytes"/> + </datatype> + <datatype> + <name name="invalid_header"/> + </datatype> + <datatype> + <name name="file_error"/> + </datatype> + </datatypes> <funcs> <func> - <name>accessible_logs() -> {[LocalLog], [DistributedLog]}</name> + <name name="accessible_logs" arity="0"/> <fsummary>Return the accessible disk logs on the current node.</fsummary> - <type> - <v>LocalLog = DistributedLog = term()</v> - </type> <desc> <p>The <c>accessible_logs/0</c> function returns the names of the disk logs accessible on the current node. @@ -195,16 +230,13 @@ </desc> </func> <func> - <name>alog(Log, Term)</name> - <name>balog(Log, Bytes) -> ok | {error, Reason}</name> + <name name="alog" arity="2"/> + <name name="balog" arity="2"/> + <type variable="Log"/> + <type variable="Term" name_i="1"/> + <type variable="Bytes"/> + <type name="notify_ret"/> <fsummary>Asynchronously log an item onto a disk log.</fsummary> - <type> - <v>Log = term()</v> - <v>Term = term()</v> - <v>Bytes = binary() | [Byte]</v> - <v>Byte = [Byte] | 0 =< integer() =< 255</v> - <v>Reason = no_such_log</v> - </type> <desc> <p>The <c>alog/2</c> and <c>balog/2</c> functions asynchronously append an item to a disk log. The function <c>alog/2</c> is @@ -225,17 +257,13 @@ </desc> </func> <func> - <name>alog_terms(Log, TermList)</name> - <name>balog_terms(Log, BytesList) -> ok | {error, Reason}</name> + <name name="alog_terms" arity="2"/> + <name name="balog_terms" arity="2"/> <fsummary>Asynchronously log several items onto a disk log.</fsummary> - <type> - <v>Log = term()</v> - <v>TermList = [term()]</v> - <v>BytesList = [Bytes]</v> - <v>Bytes = binary() | [Byte]</v> - <v>Byte = [Byte] | 0 =< integer() =< 255</v> - <v>Reason = no_such_log</v> - </type> + <type variable="Log"/> + <type variable="TermList" name_i="1"/> + <type variable="ByteList"/> + <type name="notify_ret"/> <desc> <p>The <c>alog_terms/2</c> and <c>balog_terms/2</c> functions asynchronously append a list of items to a disk log. @@ -257,14 +285,10 @@ </desc> </func> <func> - <name>block(Log)</name> - <name>block(Log, QueueLogRecords) -> ok | {error, Reason}</name> + <name name="block" arity="1"/> + <name name="block" arity="2"/> + <type name="block_error_rsn"/> <fsummary>Block a disk log.</fsummary> - <type> - <v>Log = term()</v> - <v>QueueLogRecords = bool()</v> - <v>Reason = no_such_log | nonode | {blocked_log, Log}</v> - </type> <desc> <p>With a call to <c>block/1,2</c> a process can block a log. If the blocking process is not an owner of the log, a temporary @@ -280,52 +304,32 @@ affected by the block. Any other attempt than those hitherto mentioned to update or read a blocked log suspends the calling process until the log is unblocked or returns an - error message <c>{blocked_log, Log}</c>, depending on - whether the value of <c>QueueLogRecords</c> is <c>true</c> - or <c>false</c>. The default value of <c>QueueLogRecords</c> + error message <c>{blocked_log, <anno>Log</anno>}</c>, depending on + whether the value of <c><anno>QueueLogRecords</anno></c> is <c>true</c> + or <c>false</c>. The default value of <c><anno>QueueLogRecords</anno></c> is <c>true</c>, which is used by <c>block/1</c>. </p> </desc> </func> <func> - <name>change_header(Log, Header) -> ok | {error, Reason}</name> + <name name="change_header" arity="2"/> <fsummary>Change the head or head_func option for an owner of a disk log.</fsummary> - <type> - <v>Log = term()</v> - <v>Header = {head, Head} | {head_func, {M,F,A}}</v> - <v>Head = none | term() | binary() | [Byte]</v> - <v>Byte = [Byte] | 0 =< integer() =< 255</v> - <v>Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {badarg, head}</v> - </type> <desc> <p>The <c>change_header/2</c> function changes the value of the <c>head</c> or <c>head_func</c> option of a disk log.</p> </desc> </func> <func> - <name>change_notify(Log, Owner, Notify) -> ok | {error, Reason}</name> + <name name="change_notify" arity="3"/> <fsummary>Change the notify option for an owner of a disk log.</fsummary> - <type> - <v>Log = term()</v> - <v>Owner = pid()</v> - <v>Notify = bool()</v> - <v>Reason = no_such_log | nonode | {blocked_log, Log} | {badarg, notify} | {not_owner, Owner}</v> - </type> <desc> <p>The <c>change_notify/3</c> function changes the value of the <c>notify</c> option for an owner of a disk log. </p> </desc> </func> <func> - <name>change_size(Log, Size) -> ok | {error, Reason}</name> + <name name="change_size" arity="2"/> <fsummary>Change the size of an open disk log.</fsummary> - <type> - <v>Log = term()</v> - <v>Size = integer() > 0 | infinity | {MaxNoBytes, MaxNoFiles}</v> - <v>MaxNoBytes = integer() > 0</v> - <v>MaxNoFiles = integer() > 0</v> - <v>Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {new_size_too_small, CurrentSize} | {badarg, size} | {file_error, FileName, FileError}</v> - </type> <desc> <p>The <c>change_size/2</c> function changes the size of an open log. For a halt log it is always possible to increase the size, @@ -363,21 +367,17 @@ </desc> </func> <func> - <name>chunk(Log, Continuation)</name> - <name>chunk(Log, Continuation, N) -> {Continuation2, Terms} | {Continuation2, Terms, Badbytes} | eof | {error, Reason}</name> - <name>bchunk(Log, Continuation)</name> - <name>bchunk(Log, Continuation, N) -> {Continuation2, Binaries} | {Continuation2, Binaries, Badbytes} | eof | {error, Reason}</name> + <name name="chunk" arity="2"/> + <name name="chunk" arity="3"/> + <name name="bchunk" arity="2"/> + <name name="bchunk" arity="3"/> <fsummary>Read a chunk of items written to a disk log.</fsummary> - <type> - <v>Log = term()</v> - <v>Continuation = start | cont()</v> - <v>N = integer() > 0 | infinity</v> - <v>Continuation2 = cont()</v> - <v>Terms = [term()]</v> - <v>Badbytes = integer()</v> - <v>Reason = no_such_log | {format_external, Log} | {blocked_log, Log} | {badarg, continuation} | {not_internal_wrap, Log} | {corrupt_log_file, FileName} | {file_error, FileName, FileError}</v> - <v>Binaries = [binary()]</v> - </type> + <type variable="Log"/> + <type variable="Continuation"/> + <type variable="N"/> + <type name="chunk_ret"/> + <type name="bchunk_ret"/> + <type name="chunk_error_rsn"/> <desc> <p>The <c>chunk/2,3</c> and <c>bchunk/2,3</c> functions make it possible to efficiently read the terms which have been @@ -394,31 +394,31 @@ individual distributed log on some other node is chosen, if such a log exists. </p> - <p>When <c>chunk/3</c> is called, <c>N</c> controls the + <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 64 kilobyte chunk are read. If less than - <c>N</c> terms are returned, this does not necessarily mean + <c><anno>N</anno></c> terms are returned, this does not necessarily mean that the end of the file has been reached. </p> <p>The <c>chunk</c> function returns a tuple - <c>{Continuation2, Terms}</c>, where <c>Terms</c> is a list - of terms found in the log. <c>Continuation2</c> is yet + <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 to any subsequent calls to <c>chunk</c>. With a series of calls to <c>chunk</c> it is possible to extract all terms from a log. </p> <p>The <c>chunk</c> function returns a tuple - <c>{Continuation2, Terms, Badbytes}</c> if the log is opened - in read-only mode and the read chunk is corrupt. <c>Badbytes</c> + <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> is the number of bytes in the file which were found not to be Erlang terms in the chunk. Note also that the log is not repaired. When trying to read chunks from a log opened in read-write mode, - the tuple <c>{corrupt_log_file, FileName}</c> is returned if the + the tuple <c>{corrupt_log_file, <anno>FileName</anno>}</c> is returned if the read chunk is corrupt. </p> <p><c>chunk</c> returns <c>eof</c> when the end of the log is - reached, or <c>{error, Reason}</c> if an error occurs. Should + reached, or <c>{error, <anno>Reason</anno>}</c> if an error occurs. Should a wrap log file be missing, a message is output on the error log. </p> <p>When <c>chunk/2,3</c> is used with wrap logs, the returned @@ -431,12 +431,8 @@ </desc> </func> <func> - <name>chunk_info(Continuation) -> InfoList | {error, Reason}</name> + <name name="chunk_info" arity="1"/> <fsummary>Return information about a chunk continuation of a disk log.</fsummary> - <type> - <v>Continuation = cont()</v> - <v>Reason = {no_continuation, Continuation}</v> - </type> <desc> <p>The <c>chunk_info/1</c> function returns the following pair describing the chunk continuation returned by @@ -444,29 +440,22 @@ </p> <list type="bulleted"> <item> - <p><c>{node, Node}</c>. Terms are read from - the disk log running on <c>Node</c>.</p> + <p><c>{node, <anno>Node</anno>}</c>. Terms are read from + the disk log running on <c><anno>Node</anno></c>.</p> </item> </list> </desc> </func> <func> - <name>chunk_step(Log, Continuation, Step) -> {ok, Continuation2} | {error, Reason}</name> + <name name="chunk_step" arity="3"/> <fsummary>Step forward or backward among the wrap log files of a disk log.</fsummary> - <type> - <v>Log = term()</v> - <v>Continuation = start | cont()</v> - <v>Step = integer()</v> - <v>Continuation2 = cont()</v> - <v>Reason = no_such_log | end_of_log | {format_external, Log} | {blocked_log, Log} | {badarg, continuation} | {file_error, FileName, FileError}</v> - </type> <desc> <p>The function <c>chunk_step</c> can be used in conjunction with <c>chunk/2,3</c> and <c>bchunk/2,3</c> to search through an internally formatted wrap log. It takes as argument a continuation as returned by <c>chunk/2,3</c>, <c>bchunk/2,3</c>, or <c>chunk_step/3</c>, and steps forward - (or backward) <c>Step</c> files in the wrap log. The + (or backward) <c><anno>Step</anno></c> files in the wrap log. The continuation returned points to the first log item in the new current file. </p> @@ -482,11 +471,9 @@ </desc> </func> <func> - <name>close(Log) -> ok | {error, Reason}</name> + <name name="close" arity="1"/> <fsummary>Close a disk log.</fsummary> - <type> - <v>Reason = no_such_log | nonode | {file_error, FileName, FileError}</v> - </type> + <type name="close_error_rsn"/> <desc> <p> <marker id="close_1"></marker> The function <c>close/1</c> closes a @@ -511,11 +498,8 @@ The function <c>close/1</c> closes a </desc> </func> <func> - <name>format_error(Error) -> Chars</name> + <name name="format_error" arity="1"/> <fsummary>Return an English description of a disk log error reply.</fsummary> - <type> - <v>Chars = [char() | Chars]</v> - </type> <desc> <p>Given the error returned by any function in this module, the function <c>format_error</c> returns a descriptive string @@ -524,11 +508,10 @@ The function <c>close/1</c> closes a </desc> </func> <func> - <name>inc_wrap_file(Log) -> ok | {error, Reason}</name> + <name name="inc_wrap_file" arity="1"/> <fsummary>Change to the next wrap log file of a disk log.</fsummary> - <type> - <v>Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {halt_log, Log} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError}</v> - </type> + <type name="inc_wrap_error_rsn"/> + <type name="invalid_header"/> <desc> <p>The <c>inc_wrap_file/1</c> function forces the internally formatted disk log to start logging to the @@ -543,8 +526,9 @@ The function <c>close/1</c> closes a </desc> </func> <func> - <name>info(Log) -> InfoList | {error, no_such_log}</name> + <name name="info" arity="1"/> <fsummary>Return information about a disk log.</fsummary> + <type name="dlog_info"/> <desc> <p>The <c>info/1</c> function returns a list of <c>{Tag, Value}</c> pairs describing the log. If there is a disk log process running @@ -556,55 +540,55 @@ The function <c>close/1</c> closes a </p> <list type="bulleted"> <item> - <p><c>{name, Log}</c>, where <c>Log</c> is the name of + <p><c>{name, <anno>Log</anno>}</c>, where <c><anno>Log</anno></c> is the name of the log as given by the <c>open/1</c> option <c>name</c>.</p> </item> <item> - <p><c>{file, File}</c>. For halt logs <c>File</c> is the - filename, and for wrap logs <c>File</c> is the base name.</p> + <p><c>{file, <anno>File</anno>}</c>. For halt logs <c><anno>File</anno></c> is the + filename, and for wrap logs <c><anno>File</anno></c> is the base name.</p> </item> <item> - <p><c>{type, Type}</c>, where <c>Type</c> is the type of + <p><c>{type, <anno>Type</anno>}</c>, where <c><anno>Type</anno></c> is the type of the log as given by the <c>open/1</c> option <c>type</c>.</p> </item> <item> - <p><c>{format, Format}</c>, where <c>Format</c> is the format + <p><c>{format, <anno>Format</anno>}</c>, where <c><anno>Format</anno></c> is the format of the log as given by the <c>open/1</c> option <c>format</c>.</p> </item> <item> - <p><c>{size, Size}</c>, where <c>Size</c> is the size + <p><c>{size, <anno>Size</anno>}</c>, where <c><anno>Size</anno></c> is the size of the log as given by the <c>open/1</c> option <c>size</c>, or the size set by <c>change_size/2</c>. The value set by <c>change_size/2</c> is reflected immediately.</p> </item> <item> - <p><c>{mode, Mode}</c>, where <c>Mode</c> is the mode + <p><c>{mode, <anno>Mode</anno>}</c>, where <c><anno>Mode</anno></c> is the mode of the log as given by the <c>open/1</c> option <c>mode</c>.</p> </item> <item> - <p><c>{owners, [{pid(), Notify}]}</c> where <c>Notify</c> + <p><c>{owners, [{pid(), <anno>Notify</anno>}]}</c> where <c><anno>Notify</anno></c> is the value set by the <c>open/1</c> option <c>notify</c> or the function <c>change_notify/3</c> for the owners of the log.</p> </item> <item> - <p><c>{users, Users}</c> where <c>Users</c> is the number + <p><c>{users, <anno>Users</anno>}</c> where <c><anno>Users</anno></c> is the number of anonymous users of the log, see the <c>open/1</c> option <seealso marker="#linkto">linkto</seealso>.</p> </item> <item> - <p><c>{status, Status}</c>, where <c>Status</c> is <c>ok</c> - or <c>{blocked, QueueLogRecords}</c> as set by the functions + <p><c>{status, <anno>Status</anno>}</c>, where <c><anno>Status</anno></c> is <c>ok</c> + or <c>{blocked, <anno>QueueLogRecords</anno>}</c> as set by the functions <c>block/1,2</c> and <c>unblock/1</c>.</p> </item> <item> - <p><c>{node, Node}</c>. The information returned by the + <p><c>{node, <anno>Node</anno>}</c>. The information returned by the current invocation of the <c>info/1</c> function has been - gathered from the disk log process running on <c>Node</c>.</p> + gathered from the disk log process running on <c><anno>Node</anno></c>.</p> </item> <item> - <p><c>{distributed, Dist}</c>. If the log is local on - the current node, then <c>Dist</c> has the value <c>local</c>, + <p><c>{distributed, <anno>Dist</anno>}</c>. If the log is local on + the current node, then <c><anno>Dist</anno></c> has the value <c>local</c>, otherwise all nodes where the log is distributed are returned as a list.</p> </item> @@ -614,16 +598,16 @@ The function <c>close/1</c> closes a </p> <list type="bulleted"> <item> - <p><c>{head, Head}</c>. Depending of the value of + <p><c>{head, <anno>Head</anno>}</c>. Depending of the value of the <c>open/1</c> options <c>head</c> and <c>head_func</c> or set by the function <c>change_header/2</c>, the value - of <c>Head</c> is <c>none</c> (default), + of <c><anno>Head</anno></c> is <c>none</c> (default), <c>{head, H}</c> (<c>head</c> option) or <c>{M,F,A}</c> (<c>head_func</c> option).</p> </item> <item> - <p><c>{no_written_items, NoWrittenItems}</c>, where - <c>NoWrittenItems</c> is the number of items + <p><c>{no_written_items, <anno>NoWrittenItems</anno>}</c>, where + <c><anno>NoWrittenItems</anno></c> is the number of items written to the log since the disk log process was created.</p> </item> </list> @@ -632,7 +616,7 @@ The function <c>close/1</c> closes a </p> <list type="bulleted"> <item> - <p><c>{full, Full}</c>, where <c>Full</c> is <c>true</c> or + <p><c>{full, <anno>Full</anno>}</c>, where <c><anno>Full</anno></c> is <c>true</c> or <c>false</c> depending on whether the halt log is full or not.</p> </item> </list> @@ -660,8 +644,8 @@ The function <c>close/1</c> closes a <c>size</c> or set by <c>change_size/2</c>.</p> </item> <item> - <p><c>{no_overflows, {SinceLogWasOpened, SinceLastInfo}}</c>, - where <c>SinceLogWasOpened</c> (<c>SinceLastInfo</c>) is + <p><c>{no_overflows, {<anno>SinceLogWasOpened</anno>, <anno>SinceLastInfo</anno>}}</c>, + where <c><anno>SinceLogWasOpened</anno></c> (<c><anno>SinceLastInfo</anno></c>) is the number of times a wrap log file has been filled up and a new one opened or <c>inc_wrap_file/1</c> has been called since the disk log was last opened (<c>info/1</c> @@ -677,21 +661,18 @@ The function <c>close/1</c> closes a </desc> </func> <func> - <name>lclose(Log)</name> - <name>lclose(Log, Node) -> ok | {error, Reason}</name> + <name name="lclose" arity="1"/> + <name name="lclose" arity="2"/> + <type name="lclose_error_rsn"/> <fsummary>Close a disk log on one node.</fsummary> - <type> - <v>Node = node()</v> - <v>Reason = no_such_log | {file_error, FileName, FileError}</v> - </type> <desc> <p>The function <c>lclose/1</c> closes a local log or an individual distributed log on the current node. The function <c>lclose/2</c> closes an individual distributed log on the specified node if the node is not the current one. - <c>lclose(Log)</c> is equivalent to - <c>lclose(Log, node())</c>. + <c>lclose(<anno>Log</anno>)</c> is equivalent to + <c>lclose(<anno>Log</anno>, node())</c>. See also <seealso marker="#close_1">close/1</seealso>. </p> <p>If there is no log with the given name @@ -700,20 +681,17 @@ The function <c>close/1</c> closes a </desc> </func> <func> - <name>log(Log, Term)</name> - <name>blog(Log, Bytes) -> ok | {error, Reason}</name> + <name name="log" arity="2"/> + <name name="blog" arity="2"/> <fsummary>Log an item onto a disk log.</fsummary> - <type> - <v>Log = term()</v> - <v>Term = term()</v> - <v>Bytes = binary() | [Byte]</v> - <v>Byte = [Byte] | 0 =< integer() =< 255</v> - <v>Reason = no_such_log | nonode | {read_only_mode, Log} | {format_external, Log} | {blocked_log, Log} | {full, Log} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError}</v> - </type> + <type variable="Log"/> + <type variable="Term" name_i="1"/> + <type variable="Bytes"/> + <type name="log_error_rsn"/> <desc> <p>The <c>log/2</c> and <c>blog/2</c> functions synchronously append a term to a disk log. They return <c>ok</c> or - <c>{error, Reason}</c> when the term has been written to + <c>{error, <anno>Reason</anno>}</c> when the term has been written to disk. If the log is distributed, <c>ok</c> is always returned, unless all nodes are down. Terms are written by means of the ordinary <c>write()</c> function of the @@ -736,17 +714,13 @@ The function <c>close/1</c> closes a </desc> </func> <func> - <name>log_terms(Log, TermList)</name> - <name>blog_terms(Log, BytesList) -> ok | {error, Reason}</name> + <name name="log_terms" arity="2"/> + <name name="blog_terms" arity="2"/> <fsummary>Log several items onto a disk log.</fsummary> - <type> - <v>Log = term()</v> - <v>TermList = [term()]</v> - <v>BytesList = [Bytes]</v> - <v>Bytes = binary() | [Byte]</v> - <v>Byte = [Byte] | 0 =< integer() =< 255</v> - <v>Reason = no_such_log | nonode | {read_only_mode, Log} | {format_external, Log} | {blocked_log, Log} | {full, Log} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError}</v> - </type> + <type variable="Log"/> + <type variable="TermList" name_i="1"/> + <type variable="BytesList"/> + <type name="log_error_rsn"/> <desc> <p>The <c>log_terms/2</c> and <c>blog_terms/2</c> functions synchronously append a list of items to the log. The benefit @@ -769,47 +743,33 @@ The function <c>close/1</c> closes a </desc> </func> <func> - <name>open(ArgL) -> OpenRet | DistOpenRet</name> + <name name="open" arity="1"/> + <type name="dlog_options"/> + <type name="dlog_option"/> + <type name="open_ret"/> + <type name="ret"/> + <type name="dist_open_ret"/> + <type name="dist_error_rsn"/> + <type name="open_error_rsn"/> + <type name="dlog_optattr"/> + <type name="dlog_size"/> <fsummary>Open a disk log file.</fsummary> - <type> - <v>ArgL = [Opt]</v> - <v>Opt = {name, term()} | {file, FileName}, {linkto, LinkTo} | {repair, Repair} | {type, Type} | {format, Format} | {size, Size} | {distributed, [Node]} | {notify, bool()} | {head, Head} | {head_func, {M,F,A}} | {mode, Mode}</v> - <v>FileName = string() | atom()</v> - <v>LinkTo = pid() | none</v> - <v>Repair = true | false | truncate</v> - <v>Type = halt | wrap</v> - <v>Format = internal | external</v> - <v>Size = integer() > 0 | infinity | {MaxNoBytes, MaxNoFiles}</v> - <v>MaxNoBytes = integer() > 0</v> - <v>MaxNoFiles = 0 < integer() < 65000</v> - <v>Rec = integer()</v> - <v>Bad = integer()</v> - <v>Head = none | term() | binary() | [Byte]</v> - <v>Byte = [Byte] | 0 =< integer() =< 255</v> - <v>Mode = read_write | read_only</v> - <v>OpenRet = Ret | {error, Reason}</v> - <v>DistOpenRet = {[{Node, Ret}], [{BadNode, {error, DistReason}}]}</v> - <v>Node = BadNode = atom()</v> - <v>Ret = {ok, Log} | {repaired, Log, {recovered, Rec}, {badbytes, Bad}}</v> - <v>DistReason = nodedown | Reason</v> - <v>Reason = no_such_log | {badarg, Arg} | {size_mismatch, CurrentSize, NewSize} | {arg_mismatch, OptionName, CurrentValue, Value} | {name_already_open, Log} | {open_read_write, Log} | {open_read_only, Log} | {need_repair, Log} | {not_a_log_file, FileName} | {invalid_index_file, FileName} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError} | {node_already_open, Log}</v> - </type> <desc> - <p>The <c>ArgL</c> parameter is a list of options which have + <p>The <c><anno>ArgL</anno></c> parameter is a list of options which have the following meanings:</p> <list type="bulleted"> <item> - <p><c>{name, Log}</c> specifies the name of the log. + <p><c>{name, <anno>Log</anno>}</c> specifies the name of the log. This is the name which must be passed on as a parameter in all subsequent logging operations. A name must always be supplied. </p> </item> <item> - <p><c>{file, FileName}</c> specifies the name of the + <p><c>{file, <anno>FileName</anno>}</c> specifies the name of the file which will be used for logged terms. If this value is omitted and the name of the log is either an atom or a string, - the file name will default to <c>lists:concat([Log, ".LOG"])</c> for halt logs. For wrap logs, this will be + the file name will default to <c>lists:concat([<anno>Log</anno>, ".LOG"])</c> for halt logs. For wrap logs, this will be the base name of the files. Each file in a wrap log will be called <c><![CDATA[<base_name>.N]]></c>, where <c>N</c> is an integer. Each wrap log will also have two files called @@ -817,22 +777,22 @@ The function <c>close/1</c> closes a </p> </item> <item> - <p><c>{linkto, LinkTo}</c>. <marker id="linkto"></marker> + <p><c>{linkto, <anno>LinkTo</anno>}</c>. <marker id="linkto"></marker> If - <c>LinkTo</c> is a pid, that pid becomes an owner of the - log. If <c>LinkTo</c> is <c>none</c> the log records + <c><anno>LinkTo</anno></c> is a pid, that pid becomes an owner of the + log. If <c><anno>LinkTo</anno></c> is <c>none</c> the log records that it is used anonymously by some process by incrementing the <c>users</c> counter. By default, the process which calls <c>open/1</c> owns the log. </p> </item> <item> - <p><c>{repair, Repair}</c>. If <c>Repair</c> is <c>true</c>, + <p><c>{repair, <anno>Repair</anno>}</c>. If <c><anno>Repair</anno></c> is <c>true</c>, the current log file will be repaired, if needed. As the restoration is initiated, a message is output on the error log. If <c>false</c> is given, no automatic repair will be attempted. Instead, the - tuple <c>{error, {need_repair, Log}}</c> is returned if an + tuple <c>{error, {need_repair, <anno>Log</anno>}}</c> is returned if an attempt is made to open a corrupt log file. If <c>truncate</c> is given, the log file will be truncated, creating an empty log. Default is @@ -841,41 +801,41 @@ If </p> </item> <item> - <p><c>{type, Type}</c> is the type of the log. Default + <p><c>{type, <anno>Type</anno>}</c> is the type of the log. Default is <c>halt</c>. </p> </item> <item> - <p><c>{format, Format}</c> specifies the format of the + <p><c>{format, <anno>Format</anno>}</c> specifies the format of the disk log. Default is <c>internal</c>. </p> </item> <item> - <p><c>{size, Size}</c> specifies the size of the log. + <p><c>{size, <anno>Size</anno>}</c> specifies the size of the log. When a halt log has reached its maximum size, all attempts to log more items are rejected. The default size is <c>infinity</c>, which for halt implies that there is no - maximum size. For wrap logs, the <c>Size</c> parameter + maximum size. For wrap logs, the <c><anno>Size</anno></c> parameter may be either a pair - <c>{MaxNoBytes, MaxNoFiles}</c> or <c>infinity</c>. In the + <c>{<anno>MaxNoBytes</anno>, <anno>MaxNoFiles</anno>}</c> or <c>infinity</c>. In the latter case, if the files of an already existing wrap log with the same name can be found, the size is read from the existing wrap log, otherwise an error is returned. - Wrap logs write at most <c>MaxNoBytes</c> bytes on each file - and use <c>MaxNoFiles</c> files before starting all over with - the first wrap log file. Regardless of <c>MaxNoBytes</c>, + Wrap logs write at most <c><anno>MaxNoBytes</anno></c> bytes on each file + and use <c><anno>MaxNoFiles</anno></c> files before starting all over with + the first wrap log file. Regardless of <c><anno>MaxNoBytes</anno></c>, at least the header (if there is one) and one item is written on each wrap log file before wrapping to the next file. When opening an existing wrap log, it is not necessary to supply a value for the option <c>Size</c>, but any supplied value must equal the current size of the log, otherwise - the tuple <c>{error, {size_mismatch, CurrentSize, NewSize}}</c> + the tuple <c>{error, {size_mismatch, <anno>CurrentSize</anno>, <anno>NewSize</anno>}}</c> is returned. </p> </item> <item> - <p><c>{distributed, Nodes}</c>. This option can be used for + <p><c>{distributed, <anno>Nodes</anno>}</c>. This option can be used for adding members to a distributed disk log. The default value is <c>[]</c>, which means that the log is local on the current node. @@ -946,10 +906,10 @@ If </list> </item> <item> - <p><c>{head, Head}</c> specifies a header to be + <p><c>{head, <anno>Head</anno>}</c> specifies a header to be written first on the log file. If the log is a wrap - log, the item <c>Head</c> is written first in each new file. - <c>Head</c> should be a term if the format is + log, the item <c><anno>Head</anno></c> is written first in each new file. + <c><anno>Head</anno></c> should be a term if the format is <c>internal</c>, and a deep list of bytes (or a binary) otherwise. Default is <c>none</c>, which means that no header is written first on the file. @@ -966,17 +926,17 @@ If </p> </item> <item> - <p><c>{mode, Mode}</c> specifies if the log is to be + <p><c>{mode, <anno>Mode</anno>}</c> specifies if the log is to be opened in read-only or read-write mode. It defaults to <c>read_write</c>. </p> </item> </list> - <p>The <c>open/1</c> function returns <c>{ok, Log}</c> if the + <p>The <c>open/1</c> function returns <c>{ok, <anno>Log</anno>}</c> if the log file was successfully opened. If the file was - successfully repaired, the tuple <c>{repaired, Log, {recovered, Rec}, {badbytes, Bad}}</c> is returned, where - <c>Rec</c> is the number of whole Erlang terms found in the - file and <c>Bad</c> is the number of bytes in the file which + successfully repaired, the tuple <c>{repaired, <anno>Log</anno>, {recovered, <anno>Rec</anno>}, {badbytes, <anno>Bad</anno>}}</c> is returned, where + <c><anno>Rec</anno></c> is the number of whole Erlang terms found in the + file and <c><anno>Bad</anno></c> is the number of bytes in the file which were non-Erlang terms. If the <c>distributed</c> parameter was given, <c>open/1</c> returns a list of successful replies and a list of erroneous replies. Each @@ -988,7 +948,7 @@ If position after the last logged item, and the logging of items will commence from there. If the format is <c>internal</c> and the existing file is not recognized as an internally - formatted log, a tuple <c>{error, {not_a_log_file, FileName}}</c> + formatted log, a tuple <c>{error, {not_a_log_file, <anno>FileName</anno>}}</c> is returned. </p> <p>The <c>open/1</c> function cannot be used for changing the @@ -1000,15 +960,15 @@ If or <c>change_size/2</c>. As a consequence, none of the options except <c>name</c> is mandatory. If some given value differs from the current value, a tuple - <c>{error, {arg_mismatch, OptionName, CurrentValue, Value}}</c> + <c>{error, {arg_mismatch, <anno>OptionName</anno>, <anno>CurrentValue</anno>, <anno>Value</anno>}}</c> is returned. Caution: an owner's attempt to open a log as owner once again is acknowledged with the return value - <c>{ok, Log}</c>, but the state of the disk log is not + <c>{ok, <anno>Log</anno>}</c>, but the state of the disk log is not affected in any way. </p> <p>If a log with a given name is local on some node, and one tries to open the log distributed on the same node, - then the tuple <c>{error, {node_already_open, Name}}</c> is + then the tuple <c>{error, {node_already_open, <anno>Log</anno>}}</c> is returned. The same tuple is returned if the log is distributed on some node, and one tries to open the log locally on the same node. Opening individual distributed disk logs for the first time @@ -1036,12 +996,8 @@ If </desc> </func> <func> - <name>pid2name(Pid) -> {ok, Log} | undefined</name> + <name name="pid2name" arity="1"/> <fsummary>Return the name of the disk log handled by a pid.</fsummary> - <type> - <v>Log = term()</v> - <v>Pid = pid()</v> - </type> <desc> <p>The <c>pid2name/1</c> function returns the name of the log given the pid of a disk log process on the current node, or @@ -1052,26 +1008,23 @@ If </desc> </func> <func> - <name>reopen(Log, File)</name> - <name>reopen(Log, File, Head)</name> - <name>breopen(Log, File, BHead) -> ok | {error, Reason}</name> + <name name="reopen" arity="2"/> + <name name="reopen" arity="3"/> + <name name="breopen" arity="3"/> <fsummary>Reopen a disk log and save the old log.</fsummary> - <type> - <v>Log = term()</v> - <v>File = string()</v> - <v>Head = term()</v> - <v>BHead = binary() | [Byte]</v> - <v>Byte = [Byte] | 0 =< integer() =< 255</v> - <v>Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {same_file_name, Log} | {invalid_index_file, FileName} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError}</v> - </type> + <type variable="Log"/> + <type variable="File" name_i="1"/> + <type variable="Head" name_i="2"/> + <type variable="BHead"/> + <type name="reopen_error_rsn"/> <desc> <p>The <c>reopen</c> functions first rename the log file - to <c>File</c> and then re-create a new log file. - In case of a wrap log, <c>File</c> is used as the base name + to <c><anno>File</anno></c> and then re-create a new log file. + In case of a wrap log, <c><anno>File</anno></c> is used as the base name of the renamed files. By default the header given to <c>open/1</c> is written first in - the newly opened log file, but if the <c>Head</c> or the - <c>BHead</c> argument is given, this item is used instead. + the newly opened log file, but if the <c><anno>Head</anno></c> or the + <c><anno>BHead</anno></c> argument is given, this item is used instead. The header argument is used once only; next time a wrap log file is opened, the header given to <c>open/1</c> is used. </p> @@ -1089,12 +1042,9 @@ If </desc> </func> <func> - <name>sync(Log) -> ok | {error, Reason}</name> + <name name="sync" arity="1"/> + <type name="sync_error_rsn"/> <fsummary>Flush the contents of a disk log to the disk.</fsummary> - <type> - <v>Log = term()</v> - <v>Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {file_error, FileName, FileError}</v> - </type> <desc> <p>The <c>sync/1</c> function ensures that the contents of the log are actually written to the disk. @@ -1103,20 +1053,17 @@ If </desc> </func> <func> - <name>truncate(Log)</name> - <name>truncate(Log, Head)</name> - <name>btruncate(Log, BHead) -> ok | {error, Reason}</name> + <name name="truncate" arity="1"/> + <name name="truncate" arity="2"/> + <name name="btruncate" arity="2"/> <fsummary>Truncate a disk log.</fsummary> - <type> - <v>Log = term()</v> - <v>Head = term()</v> - <v>BHead = binary() | [Byte]</v> - <v>Byte = [Byte] | 0 =< integer() =< 255</v> - <v>Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError}</v> - </type> + <type variable="Log"/> + <type variable="Head" name_i="2"/> + <type variable="BHead"/> + <type name="trunc_error_rsn"/> <desc> <p>The <c>truncate</c> functions remove all items from a disk log. - If the <c>Head</c> or the <c>BHead</c> argument is + If the <c><anno>Head</anno></c> or the <c><anno>BHead</anno></c> argument is given, this item is written first in the newly truncated log, otherwise the header given to <c>open/1</c> is used. The header argument is only used once; next time a wrap log file @@ -1138,12 +1085,9 @@ If </desc> </func> <func> - <name>unblock(Log) -> ok | {error, Reason}</name> + <name name="unblock" arity="1"/> + <type name="unblock_error_rsn"/> <fsummary>Unblock a disk log.</fsummary> - <type> - <v>Log = term()</v> - <v>Reason = no_such_log | nonode | {not_blocked, Log} | {not_blocked_by_pid, Log}</v> - </type> <desc> <p>The <c>unblock/1</c> function unblocks a log. A log can only be unblocked by the blocking process. @@ -1159,4 +1103,3 @@ If <seealso marker="wrap_log_reader">wrap_log_reader(3)</seealso></p> </section> </erlref> - |