# Module Linebuf

    module Linebuf: sig .. end

Line-by-line reading of a file. A line buffer allows one to read one line of a file at a time, blocking until a line is available. Line buffers are distinct from Pervasives.read_line in that they "notice" new data arriving in the file more quickly.

    type t

The type of a line buffer.

    type error_type =

`|` | `Null_retry`
`|` | `Too_many_nulls`
`|` | `Exception of `string * exn``

    type lnum =

`|` | `Known of `int``
`|` | `Unknown`

    type result =

`|` | `Success of `lnum * string``
`|` | `Nothing_available`
`|` | `Error of `error_type``
`|` | `Fatal_error of `string * exn``

    exception File_truncated_or_deleted

    val create : ?pos:Int64.t ->
           ?close_on_eof:bool ->
           ?null_hack:[ `Off | `Retry | `Retry_then_fail ] ->
           ?eprint_nulls:bool ->
           ?follow_deletes:bool ->
           ?signal_on_truncate_or_delete:bool -> string -> t

Open a line buffer from the passed filename. If `close_on_eof` is set, when `eof` is read, the file will be closed and reopened if necessary. if `follow_deletes` is set, then when `eof` is read linebuf will stat the file, and if it has been deleted and recreated it will open the new file. If `eprint_nulls` is set, then when nulls are found, a warning message will be printed to stderr. `null_hack` specifies the behaviour of the linebuf upon reception of null characters in the file (as seen when tailing files over CIFS). Null hack options: `Off: don't check for nulls, just keep going. `Retry: close and reopen file when nulls are read from the file. If max_null_retries is reached, then pass the line with nulls. `Retry_then_fail: the same as retry, except that an exception is raised once max_null_retries is reached.

    val close : t -> unit

Closes the line buffer (and the underlying file).

    val is_closed : t -> bool

Returns whether or not the line buffer is closed

    val try_read : t -> string option

Tries to read a line from the file. If no more lines are available, returns `None`.

    val try_read_lnum : t -> (lnum * string) option

`try_read_lnum` is like `try_read` except also provides the line number of the read line.

    val try_read_lnum_verbose : t -> result

Like try_read, except that it returns more verbose errors

    val read : t -> string

Calls try_read every 0.01 seconds and returns when a line is available.

    val tail : t -> unit

Seeks to the end of the file and blocks until another line is available -- this new line is not returned. Successive return values of `try_read_lnum` and `try_read_lnum` will return `Unknown` as the current line number until `reset` is called

    val unsafe_tail : t -> unit

Same as `tail` except it may return before a new line is available on the file i.e. it (usually) doesn't block. Note that this does interact with files in a fairly naive way, so there's no guarantee that it absolutely doesn't block.

Note that when this functions is called, the next line that's read may be a partial line. After that first line, only full lines will be read.

    val name : t -> string

    val reset : t -> unit

reopens the file and seeks to the beginning. Also recovers the ability to get line numbers if `tail` has been called