Module Netfs

module Netfs: sig .. end

Class type stream_fs for filesystems with stream access to files

---

The class type Netfs.stream_fs is an abstraction for both kernel-level and user-level filesystems. It is used as parameter for algorithms (like globbing) that operate on filesystems but do not want to assume any particular filesystem. Only stream access is provided (no seek).

File paths:

The filesystem supports hierarchical file names. File paths use Unix conventions, i.e.

• / is the root
• Path components are separated by slashes. Several consecutive slashes are allowed but mean the same as a single slash.
• . is the same directory
• .. is the parent directory

All paths need to be absolute (i.e. start with /).

There can be additional constraints on paths:

• Character encoding restriction: A certain ASCII-compatible character encoding is assumed (including UTF-8)
• Character exclusion: Certain characters may be excluded

Implementations may impose more constraints that cannot be expressed here (case insensitivity, path length, exclusion of special names etc.).

Virtuality:

There is no assumption that / is the real root of the local filesystem. It can actually be anywhere - a local subdirectory, or a remote directory, or a fictive root. There needs not to be any protection against "running beyond root", e.g. with the path /...

This class type also supports remote filesystems, and thus there is no concept of file handle (because this would exclude a number of implementations).

Errors:

Errors should generally be indicated by raising Unix_error. For many error codes the interpretation is already given by POSIX. Here are some more special cases:

• EINVAL: should also be used for invalid paths, or when a flag cannot be supported (and it is non-ignorable)
• ENOSYS: should also be used if an operation is generally unavailable

In case of hard errors (like socket errors when communicating with the remote server) there is no need to stick to Unix_error, though.

Subtyping:

The class type Netfs.stream_fs is subtypable, and subtypes can add more features by:

• adding more methods
• adding more flags to existing methods

Omitted:

Real filesystems usually provide a lot more features than what is represented here, such as:

• Access control and file permissions
• Metadata like timestamps
• Random access to files

This definition here is intentionally minimalistic. In the future more extended versions of this class type may be defined that cover more common filesystem features.

The class type stream_fs

type read_flag = [ `Binary | `Dummy | `Skip of int64 | `Streaming ] 

type write_flag = [ `Binary | `Create | `Dummy | `Exclusive | `Streaming | `Truncate ] 

type size_flag = [ `Dummy ] 

type test_flag = [ `Dummy | `Link ] 

type remove_flag = [ `Dummy | `Recursive ] 

type rename_flag = [ `Dummy ] 

type symlink_flag = [ `Dummy ] 

type readdir_flag = [ `Dummy ] 

type readlink_flag = [ `Dummy ] 

type mkdir_flag = [ `Dummy | `Nonexcl | `Path ] 

type rmdir_flag = [ `Dummy ] 

type copy_flag = [ `Dummy ] 

Note `Dummy: this flag is always ignored. There are two reasons for having it:

• Ocaml does not allow empty variants
• it is sometimes convenient to have it (e.g. in: if <condition> then `Create else `Dummy)

type test_type = [ `D | `E | `F | `H | `N | `R | `S | `W | `X ] 

class type stream_fs = object .. end

val local_fs : ?encoding:Netconversion.encoding -> ?root:string -> unit -> stream_fs

OS Notes

Unix in general: There is no notion of character encoding of paths. Paths are just bytes. Because of this, the default encoding is None. If a different encoding is passed to local_fs, these bytes are just interpreted in this encoding. There is no conversion.

For desktop programs, though, usually the character encoding of the locale is taken for filenames. You can get this by passing

    let encoding = 
      Netconversion.user_encoding()
    

as encoding argument.

Windows: If the root argument is not passed to local_fs it is possible to access the whole filesystem:

• Paths starting with drive letters like c:/ are also considered as absolute
• Additionally, paths starting with slashes like /c:/ mean the same
• UNC paths starting with two slashes like //hostname are supported

However, when a root directory is passed, these additional notations are not possible anymore - paths must start with /, and there is neither support for drive letters nor for UNC paths.

The encoding arg defaults to current ANSI codepage, and it is not supported to request a different encoding. (The difficulty is that the Win32 bindings of the relevant OS functions always assume the ANSI encoding.)

There is no support for backslashes as path separators (such paths will be rejected), for better compatibility with other platforms.

Other impementations of stream_fs

List:

• Http_fs allows one to access HTTP-based filesystems
• Shell_fs allows one to access filesystems by executing shell commands. This works locally and via ssh.

Algorithms

val copy : ?replace:bool ->
       ?streaming:bool ->
       stream_fs -> string -> stream_fs -> string -> unit

val copy_into : ?replace:bool ->
       ?subst:(int -> string) ->
       ?streaming:bool ->
       stream_fs -> string -> stream_fs -> string -> unit

type file_kind = [ `Directory | `None | `Other | `Regular | `Symlink ] 

val iter : pre:(string -> file_kind -> file_kind -> unit) ->
       ?post:(string -> unit) -> stream_fs -> string -> unit

val convert_path : ?subst:(int -> string) ->
       stream_fs -> stream_fs -> string -> string

This web site is published by Informatikbüro Gerd Stolpmann