|
|
Эта страница руководства для версии 10.9 Mac OS XЕсли Вы выполняете различную версию Mac OS X, просматриваете документацию локально:
Читать страницы руководстваСтраницы руководства предназначаются как справочник для людей, уже понимающих технологию.
|
vfs-fsapi(n) vfs-fsapi(n)
____________________________________________________________________________________________________________
NAME
vfs-fsapi - API for the implementation of a filesystem in Tcl
SYNOPSIS
package require Tcl 8.4
package require vfs ?1.2.1?
vfshandler subcmd root relative actualpath args...
vfshandler access root relative actualpath mode
vfshandler createdirectory root relative actualpath
vfshandler deletefile root relative actualpath
vfshandler fileattributes root relative actualpath ?index? ?value?
vfshandler matchindirectory root relative actualpath pattern types
vfshandler open root relative actualpath mode permissions
vfshandler removedirectory root relative actualpath recursive
vfshandler stat root relative actualpath
vfshandler utime root relative actualpath actime mtime
vfs::accessMode mode
vfs::matchDirectories types
vfs::matchFiles types
vfs::matchCorrectTypes types filelist ?inDir?
____________________________________________________________________________________________________________
DESCRIPTION
This document explains the API used by the package vfs to communicate with filesystem implementations
written in tcl.
HANDLER OVERVIEW
The package vfs intercepts every filesystem operation which falls within a given mount point, and
passes the operation on to the mount point's vfshandler command in the interpreter which registered
it.
If the handler takes appropriate action for each of the cases it is called for, a complete, perfect
virtual filesystem will be achieved, indistinguishable to Tcl from the native filesystem. (CAVEATS:
Right now vfs does not expose to Tcl all the permission-related flags of glob).
vfshandler subcmd root relative actualpath args...
The first argument specifies the operation to perform on behalf of the filesystem code in the
tcl core, the remainder specify the file path on which to operate, in different forms, and
parts, and any additional arguments which may be required to carry out the action.
To demonstrate the treatment of a path by the generic layer we use
"C:/foo/bar/mount.zip/xxx/yyy" as an example and additionally assume that the following condi-tions conditions
tions are true:
[1] "mount.zip" is a zip archive which has been mounted on top of itself,
[2] said zip archive contains a file with path "xxx/yyy",
[3] the current working directory of the application is inside of directory "xxx",
[4] and the command executed is file exists yyy.
The file separator between root and relative is omitted. Most filesystem operations need only the
relative argument for their correct operation, but some actually require the other parts of the path.
subcmd This argument of the handler can be one of the following access, createdirectory,
deletefile, fileattributes, matchindirectory, open, removedirectory, stat, or utime.
The generic layer expects that the subcommands of a handler signal error conditions by
calling vfs::filesystem posixerror with the appropriate posix error code instead of
throwing a tcl error. If the latter is done nevertheless it will be treated as an
unknown posix error.
There are three exceptions to the rule above: If any of open (when an interpreter is
given), matchindirectory, and fileattributes (for a set or get operation only) throw a
tcl error, this error will be passed up to the caller of the filesystem command which
invoked the handler. Note that this does not preclude the ability of these subcommands
to use the command vfs::filesystem posixerror to report more regular filesystem errors.
root Part of the specification of the path to operate upon. It contains the part of the path
which lies outside this filesystem's mount point. For example outlined above its value
will be "C:/foo/bar/mount.zip".
relative
Part of the specification of the path to operate upon. It contains the part of the path
which lies inside this filesystem. For example outlined above its value will be
"xxx/yyy".
actualpath
Part of the specification of the path to operate upon. It contains the original (unnor-malized) (unnormalized)
malized) name of the path which was used in the current command wherever it originated
(in Tcl or C). For example outlined above its value will be "yyy".
HANDLER METHODS
vfshandler access root relative actualpath mode
Signal a posix error if the specified access mode (an integer number) is not compatible with
the file or directory described by the path. The generic layer will ignore any non-empty
return value.
The command vfs::accessMode (see section HANDLER ENVIRONMENT) can be used to convert the inte-ger integer
ger mode into an easier to check string value.
vfshandler createdirectory root relative actualpath
Create a directory with the given name. The command can assume that all sub-directories in
the path exist and are valid, and that the actual desired path does not yet exist (Tcl takes
care of all of that for us).
vfshandler deletefile root relative actualpath
Delete the given file.
vfshandler fileattributes root relative actualpath ?index? ?value?
The command has to return a list containing the names of all acceptable attributes, if neither
index nor value were specified.
The command has to return the value of the index'th attribute if the index is specified, but
not the value. The attributes are counted in the same order as their names appear in the list
returned by a call where neither index nor value were specified. The first attribute is has
the index 0.
The command has to set the value of the index'th attribute to value if both index and value
were specified for the call.
vfshandler matchindirectory root relative actualpath pattern types
Return the list of files or directories in the given path which match the glob pattern and are
compatible with the specified list of types. The specified path is always the name of an
existing directory.
Note: As Tcl generates requests for directory-only matches from the filesystems involved when
performing any type of recursive globbing this subcommand absolutely has to handle such (and
file-only) requests correctly or bad things (TM) will happen.
The commands vfs::matchDirectories and vfs::matchFiles (see section HANDLER ENVIRONMENT) can
aid the implementation greatly in this task.
vfshandler open root relative actualpath mode permissions
Either returns a list describing the successfully opened file, or throws an error describing
how the operation failed.
The list returned upon success contains at least one and at most two elements. The first,
obligatory, element is always the handle of the channel which was created to allow access to
the contents of the file.
If specified the second element will be interpreted as a callback, i.e. a command prefix. This
prefix will always be executed as is, i.e. without additional arguments. Any required argu-ments arguments
ments have to be returned as part of the result of the call to open.
If present the specified callback will be evaluated just before the channel is closed by the
generic filesystem layer. The callback itself must not call close.
The channel however is live enough to allow seek and read operations. In addition all avail-able available
able data will have been flushed into it already. This means, for example, that the callback
can seek to the beginning of the said channel, read its contents and then store the gathered
data elsewhere. In other words, this callback is not only crucial to the cleanup of any
resources associated with an opened file, but also for the ability to implement a filesystem
which can be written to.
Under normal circumstances return code and any errors thrown by the callback itself are
ignored. In that case errors have to be signaled asychronously, for example by calling bger-ror. bgerror.
ror. However if, through a call of the subcommand internalerror, an error handling script has
been specified for the file system, all errors thrown here will be passed to that script for
further action.
mode can be any of r, w, a, w+, or a+.
permissions
determines the native mode the openend file is created with. Relevant only of the open
mode actually requests the creation of a non-existing file, i.e. is not r.
vfshandler removedirectory root relative actualpath recursive
Delete the given directory. Argument recursive is a boolean. If the specified value is true
then even if the directory is non-empty, an attempt has to be made to recursively delete it
and its contents. If the spcified value is false and the directory is non-empty, a posix
error (EEXIST) has to be thrown.
vfshandler stat root relative actualpath
The result has to be a list of keys and values, in a format acceptable to the builtin command
array set. It describes the contents of a stat structure. The order of the keys in the list is
not important.
Given this the subcommand should use something like
return [list dev 0 type file mtime 1234 ...].
as the last command of its implementation.
The following keys and their values have to be supplied by the filesystem:
dev A long integer number, the device number of the path stat was called for.
ino A long integer number, the inode number of the path stat was called for. Each path
handled by the filesystem should be uniquely identified by the combination of device
and inode number. Violating this principle will cause higher-level algorithms
which(have to) keep track of device and inode information to fail in all manners possi-ble. possible.
ble.
An example of such an algorithm would be a directory walker using device/inode informa-tion information
tion to keep itself out of infinite loops generated through symbolic links. Returning
non-unique device/inode information will most likely cause such a walker to skip over
paths under the wrong assumption of having them seen already.
mode An integer number, the access mode of the path. It is this mode which is checked by the
subcommand access.
nlink A long integer number, the number of hard links to the specified path.
uid A long integer number, the id of the user owning the virtual path.
gid A long integer number, the id of the user group the virtual path belongs to.
size A long integer number, the true size of the virtual path, in bytes.
atime A long integer number, the time of the latest access to the path, in seconds since the
epoch. Convertible into a readable date/time by the command clock format.
mtime A long integer number, the time of the latest modification of the path, in seconds
since the epoch. Convertible into a readable date/time by the command clock format.
ctime A long integer number, the time of the path was created, in seconds since the epoch.
Convertible into a readable date/time by the command clock format.
type A string, either directory, or file, describing the type of the given path.
vfshandler utime root relative actualpath actime mtime
Set the access and modification times of the given file (these are read with stat).
HANDLER ENVIRONMENT
The implementation of a filesystem handler can rely on the existence of the following utility com-mands: commands:
mands:
vfs::accessMode mode
This commands converts an access mode given as integer into a string, one of F, X, W, XW, R,
RX, and RW.
vfs::matchDirectories types
Checks if the glob types specification ask for the inclusion of directories. Returns a boolean
result. true is returned if types does ask for directories, else false.
vfs::matchFiles types
Checks if the glob types specification ask for the inclusion of files. Returns a boolean
result. true is returned if types does ask for directories, else false.
vfs::matchCorrectTypes types filelist ?inDir?
Returns that subset of the filelist which are compatible with the types given. The elements of
filelist are either absolute paths, or names of files in the directory indir. The latter
interpretation is taken if and only if the argument indir is specified.
FILESYSTEM DEBUGGING
To debug a problem in the implementation of a filesystem use code as shown below. This registers the
command report as the error handler for the filesystem, which in turn prints out the error stack pro-vided provided
vided by tcl.
vfs::filesystem internalerror report
proc report {} {
puts stderr $::errorInfo
}
SEE ALSO
vfs, vfs-filesystems
KEYWORDS
file, filesystem, vfs
COPYRIGHT
Copyright (c) 2001-2003 Vince Darley <vincentdarley@users.sourceforge.net>
Copyright (c) 2003 Andreas Kupries <andreas_kupries@users.sourceforge.net>
Tcl-level Virtual Filesystems 1.0 vfs-fsapi(n)
|
Сообщение о проблемах
Способ сообщить о проблеме с этой страницей руководства зависит от типа проблемы:
- Ошибки содержания
- Ошибки отчета в содержании этой документации со ссылками на отзыв ниже.
- Отчеты об ошибках
- Сообщите об ошибках в функциональности описанного инструмента или API через Генератор отчетов Ошибки.
- Форматирование проблем
- Отчет, форматирующий ошибки в интерактивной версии этих страниц со ссылками на отзыв ниже.