Ocamlnet 3 Reference Manual : Netfs.stream_fs

# Class type Netfs.stream_fs

    class type stream_fs = object .. end

    method path_encoding : Netconversion.encoding option

The encoding must be ASCII-compatible (`Netconversion.is_ascii_compatible`). If `None` the ASCII encoding is assumed for codes 0-127, and no meaning is defined for byte codes 128-255.

    method path_exclusions : (int * int) list

Code points that must not occur in path components between slashes. This is given as ranges `(from,to)`. The code points are interpreted as Unicode code points if an encoding is available, and as byte codes otherwise. For example, for Unix the code points 0 and 47 (slash) are normally the only excluded code points.

    method nominal_dot_dot : bool

Whether the effect of `..` can be obtained by stripping off the last path component, i.e. whether `Filename.dirname path <=> path ^ "/.."`

    method read : read_flag list -> string -> Netchannels.in_obj_channel

`read flags filename`: Opens the file `filename` for reading, and returns the input stream. Flags:

- ``Skip n`: Skips the first `n` bytes of the file. On many filesystems this is more efficient than reading `n` bytes and dropping them; however, there is no guarantee that this optimization exists.
- ``Binary`: Opens the file in binary mode (if there is such a distinction)
- ``Streaming` for network filesystems: If possible, open the file in streaming mode, and avoid to copy the whole file to the local disk before returning the `Netchannels.in_obj_channel`. Streaming mode is faster, but has also downsides. Especially, the implementation of `read` can do less to recover from transient network problems (like retrying the whole download). Support for this flag is optional, and it is ignored if there is no extra streaming mode.

    method read_file : read_file_flag list -> string -> local_file

`read_file flags filename`: Opens the file `filename` for reading, and returns the contents as a `local_file`. Use the method `filename` to get the file name of the local file. The file may be temporary, but this is not required. The method `close` of the returned object should be called when the file is no longer needed. In case of a temporary file, the file can then be deleted. Flags:

- ``Binary`: Opens the file in binary mode (if there is such a distinction)

    method write : write_flag list -> string -> Netchannels.out_obj_channel

`write flags filename`: Opens (and optionally creates) the `filename` for writing, and returns the output stream. Flags:

- ``Create`: If the file does not exist, create it
- ``Truncate`: If the file exists, truncate it to zero before writing
- ``Exclusive`: The ``Create` is done exclusively
- ``Binary`: Opens the file in binary mode (if there is such a distinction)
- ``Streaming`: see `read` (above) for explanations

Some filesystems refuse this operation if neither ``Create` nor ``Truncate` is specified because overwriting an existing file is not supported. There are also filesystems that cannot even modify files by truncating them first, but only allow to write to new files.

It is unspecified whether the file appears in the directory directly after calling `write` or first when the stream is closed.

    method write_file : write_file_flag list -> string -> local_file -> unit

`write_file flags filename localfile`: Opens the file `filename` for writing, and copies the contents of the `localfile` to it. It is ensured that the method `close` of `localfile` is called once the operation is finished (whether successful or not). Flags:

- ``Create`: If the (remote) file does not exist, create it
- ``Truncate`: If the file exists, truncate it to zero before writing
- ``Exclusive`: The ``Create` is done exclusively
- ``Binary`: Opens the file in binary mode (if there is such a distinction)
- ``Link`: Allows that the destination file is created as a hard link of the original file. This is tried whatever other mode is specified. If not successful, a copy is done instead.

    method size : size_flag list -> string -> int64

Returns the size of a file. Note that there is intentionally no distinction between text and binary mode - implementations must always assume binary mode.

    method test : test_flag list -> string -> test_type -> bool

Returns whether the test is true. For filesystems that know symbolic links, the test operation normally follows symlinks (except for the ``N` and ``H` tests). By specifying the ``Link` flag symlinks are not followed.

    method test_list : test_flag list -> string -> test_type list -> bool list

Similar to `test` but this function performs all tests in the list at once, and returns a bool for each test.

    method remove : remove_flag list -> string -> unit

Removes the file or symlink. Implementation are free to also support the removal of empty directories.

Flags:

- ``Recursive`: Remove the contents of the non-empty directory recursively. This is an optional feature. There needs not to be any protection against operations done by other processes that affect the directory tree being deleted.

    method rename : rename_flag list -> string -> string -> unit

Renames the file. There is no guarantee that a rename is atomic

    method symlink : symlink_flag list -> string -> string -> unit

`symlink flags oldpath newpath`: Creates a symlink. This is an exclusive create, i.e. the operation fails if `newpath` already exists.

    method readdir : readdir_flag list -> string -> string list

Reads the contents of a directory. Whether "." and ".." are returned is platform-dependent. The entries can be returned in any order.

    method readlink : readlink_flag list -> string -> string

Reads the target of a symlink

    method mkdir : mkdir_flag list -> string -> unit

Creates a new directory. Flags:

- ``Path`: Creates missing parent directories. This is an optional feature. (If not supported, ENOENT is reported.)
- ``Nonexcl`: Non-exclusive create.

    method rmdir : rmdir_flag list -> string -> unit

Removes an empty directory

    method copy : copy_flag list -> string -> string -> unit

Copies a file to a new name. This does not descent into directories. Also, symlinks are resolved, and the linked file is copied.

    method cancel : unit -> unit

Cancels any ongoing `write`. The user must also call the `close_out` method after cancelling. The effect is that after the close no more network activity will occur.