Attachment "docs_tcl_C-fun1.patch" to
ticket [1022527fff]
added by
mkolesn
2004-09-11 17:13:44.
Index: OpenFileChnl.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/OpenFileChnl.3,v
retrieving revision 1.25
diff -u -r1.25 OpenFileChnl.3
--- OpenFileChnl.3 16 Jul 2004 22:22:35 -0000 1.25
+++ OpenFileChnl.3 11 Sep 2004 09:50:56 -0000
@@ -227,7 +227,7 @@
and output operations on a variety of file, socket, and device
types.
The channel mechanism is extensible to new channel types, by
-providing a low level channel driver for the new type; the channel driver
+providing a low-level channel driver for the new type; the channel driver
interface is described in the manual entry for \fBTcl_CreateChannel\fR. The
channel mechanism provides a buffering scheme modeled after
Unix's standard I/O, and it also allows for nonblocking I/O on
@@ -342,13 +342,13 @@
\fBTcl_RegisterChannel\fR with \fIinterp\fR as NULL, to indicate that it
wishes to hold a reference to this channel. Subsequently, the channel can
be registered in a Tcl interpreter and it will only be closed when the
-matching number of calls to \fBTcl_UnregisterChannel\fR have been made.
+matching number of calls to \fBTcl_UnregisterChannel\fR has been made.
This allows code executing outside of any interpreter to safely hold a
reference to a channel that is also registered in a Tcl interpreter.
.PP
This procedure interacts with the code managing the standard
channels. If no standard channels were initialized before the first
-call to \fBTcl_RegisterChannel\fR they will get initialized by that
+call to \fBTcl_RegisterChannel\fR, they will get initialized by that
call. See \fBTcl_StandardChannels\fR for a general treatise about
standard channels and the behaviour of the Tcl library with regard to
them.
Index: FileSystem.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/FileSystem.3,v
retrieving revision 1.45
diff -u -r1.45 FileSystem.3
--- FileSystem.3 31 Aug 2004 09:20:09 -0000 1.45
+++ FileSystem.3 11 Sep 2004 09:05:24 -0000
@@ -152,14 +152,14 @@
question. If the object does not already have an internal \fBpath\fR
representation, it will be converted to have one.
.AP Tcl_Obj *srcPathPtr in
-As for \fBpathPtr\fR, but used for the source file for a copy or
+As for \fIpathPtr\fR, but used for the source file for a copy or
rename operation.
.AP Tcl_Obj *destPathPtr in
-As for \fBpathPtr\fR, but used for the destination filename for a copy or
+As for \fIpathPtr\fR, but used for the destination filename for a copy or
rename operation.
.AP "CONST char" *encodingName in
The encoding of the data stored in the
-file identified by \fBpathPtr\fR and to be evaluted.
+file identified by \fIpathPtr\fR and to be evaluated.
.AP "CONST char" *pattern in
Only files or directories matching this pattern will be returned by
\fBTcl_FSMatchInDirectory\fR.
@@ -182,7 +182,7 @@
.AP Tcl_Obj *listObj in
The list of path elements to operate on with a \fBjoin\fR operation.
.AP int elements in
-If non-negative, the number of elements in the listObj which should
+If non-negative, the number of elements in the \fIlistObj\fR which should
be joined together. If negative, then all elements are joined.
.AP Tcl_Obj **errorPtr out
In the case of an error, filled with an object containing the name of
@@ -190,7 +190,7 @@
.AP Tcl_Obj **objPtrRef out
Filled with an object containing the result of the operation.
.AP Tcl_Obj *result out
-Pre-allocated object in which to store (by lappending) the list of
+Pre-allocated object in which to store (by \fBlappend\fRing) the list of
files or directories which are successfully matched in
\fBTcl_FSMatchInDirectory\fR.
.AP int mode in
@@ -234,7 +234,7 @@
.SH DESCRIPTION
.PP
-There are several reasons for calling the \fBTcl_FS...\fR functions
+There are several reasons for calling the Tcl_FS API functions
rather than calling system level functions like \fBaccess\fR and
\fBstat\fR directly. First, they will work cross-platform, so an
extension which calls them should work unmodified on Unix and
@@ -244,18 +244,18 @@
required (and may cache the results of such conversions for greater
efficiency on subsequent calls). Fourth, and perhaps most importantly,
all of these functions are 'virtual filesystem aware'. Any virtual
-filesystem which has been registered (through
+filesystem (VFS for short) which has been registered (through
\fBTcl_FSRegister\fR) may reroute file access to alternative
media or access methods. This means that all of these functions (and
therefore the corresponding \fBfile\fR, \fBglob\fR, \fBpwd\fR, \fBcd\fR,
\fBopen\fR, etc. Tcl commands) may be operate on 'files' which are not
native files in the native filesystem. This also means that any Tcl
-extension which accesses the filesystem through this API is
+extension which accesses the filesystem (FS for short) through this API is
automatically 'virtual filesystem aware'. Of course, if an extension
accesses the native filesystem directly (through platform-specific
APIs, for example), then Tcl cannot intercept such calls.
.PP
-If appropriate vfs's have been registered, the 'files' may, to give two
+If appropriate VFSs have been registered, the 'files' may, to give two
examples, be remote (e.g. situated on a remote ftp server) or archived
(e.g. lying inside a .zip archive). Such registered filesystems provide
a lookup table of functions to implement all or some of the functionality
@@ -264,7 +264,7 @@
declared to be, allowing the same code to be used both on systems with
and systems without support for files larger than 2GB in size.
.PP
-The \fBTcl_FS...\fR are objectified and may cache internal
+The Tcl_FS API is objectified and may cache internal
representations and other path-related strings (e.g. the current working
directory). One side-effect of this is that one must not pass in objects
with a refCount of zero to any of these functions. If such calls were
@@ -272,49 +272,49 @@
in memory leaks (under some circumstances, the filesystem code may wish
to retain a reference to the passed in object, and so one must not assume
that after any of these calls return, the object still has a refCount of
-zero - it may have been incremented), or in a direct segfault
+zero - it may have been incremented), or in a direct SegFault
due to the object being freed part way through the complex object
manipulation required to ensure that the path is fully normalized and
absolute for filesystem determination. The practical lesson to learn
from this is that \fBTcl_Obj *path = Tcl_NewStringObj(...) ;
-Tcl_FS...(path) ; Tcl_DecrRefCount(path)\fR is wrong, and may segfault.
+Tcl_FSWhatever(path) ; Tcl_DecrRefCount(path)\fR is wrong, and may SegFault.
The 'path' must have its refCount incremented before passing it in, or
decrementing it. For this reason, objects with a refCount of zero are
considered not to be valid filesystem paths and calling any Tcl_FS API
-with such an object will result in no action being taken.
+function with such an object will result in no action being taken.
.PP
-\fBTcl_FSCopyFile\fR attempts to copy the file given by srcPathPtr to the
-path name given by destPathPtr. If the two paths given lie in the same
+\fBTcl_FSCopyFile\fR attempts to copy the file given by \fIsrcPathPtr\fR to the
+path name given by \fIdestPathPtr\fR. If the two paths given lie in the same
filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that
filesystem's 'copy file' function is called (if it is non-NULL).
-Otherwise the function returns -1 and sets Tcl's errno to the 'EXDEV'
-posix error code (which signifies a 'cross-domain link').
+Otherwise the function returns -1 and sets Tcl's \fBerrno\fR to the 'EXDEV'
+POSIX error code (which signifies a 'cross-domain link').
.PP
-\fBTcl_FSCopyDirectory\fR attempts to copy the directory given by srcPathPtr to the
-path name given by destPathPtr. If the two paths given lie in the same
+\fBTcl_FSCopyDirectory\fR attempts to copy the directory given by \fIsrcPathPtr\fR to the
+path name given by \fIdestPathPtr\fR. If the two paths given lie in the same
filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that
filesystem's 'copy file' function is called (if it is non-NULL).
-Otherwise the function returns -1 and sets Tcl's errno to the 'EXDEV'
-posix error code (which signifies a 'cross-domain link').
+Otherwise the function returns -1 and sets Tcl's \fBerrno\fR to the 'EXDEV'
+POSIX error code (which signifies a 'cross-domain link').
.PP
\fBTcl_FSCreateDirectory\fR attempts to create the directory given by
-pathPtr by calling the owning filesystem's 'create directory'
+\fIpathPtr\fR by calling the owning filesystem's 'create directory'
function.
.PP
\fBTcl_FSDeleteFile\fR attempts to delete the file given by
-pathPtr by calling the owning filesystem's 'delete file'
+\fIpathPtr\fR by calling the owning filesystem's 'delete file'
function.
.PP
\fBTcl_FSRemoveDirectory\fR attempts to remove the directory given by
-pathPtr by calling the owning filesystem's 'remove directory'
+\fIpathPtr\fR by calling the owning filesystem's 'remove directory'
function.
.PP
\fBTcl_FSRenameFile\fR attempts to rename the file or directory given by
-srcPathPtr to the path name given by destPathPtr. If the two paths
+\fIsrcPathPtr\fR to the path name given by \fIdestPathPtr\fR. If the two paths
given lie in the same filesystem (according to
\fBTcl_FSGetFileSystemForPath\fR) then that filesystem's 'rename file'
function is called (if it is non-NULL). Otherwise the function returns -1
-and sets Tcl's errno to the 'EXDEV' posix error code (which signifies
+and sets Tcl's \fBerrno\fR to the 'EXDEV' POSIX error code (which signifies
a ``cross-domain link'').
.PP
\fBTcl_FSListVolumes\fR calls each filesystem which has a non-NULL 'list
@@ -324,10 +324,10 @@
.PP
.VS 8.5
\fBTcl_FSEvalFileEx\fR reads the file given by \fIpathPtr\fR using
-the encoding identified by \fBencodingName\fR and evaluates
+the encoding identified by \fIencodingName\fR and evaluates
its contents as a Tcl script. It returns the same information as
\fBTcl_EvalObjEx\fR.
-If \fBencodingName\fR is NULL, the system encoding is used for
+If \fIencodingName\fR is NULL, the system encoding is used for
reading the file contents.
If the file couldn't be read then a Tcl error is returned to describe
why the file couldn't be read.
@@ -342,40 +342,40 @@
.PP
\fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and
returns the addresses of two procedures within that file, if they are
-defined. The appropriate function for the filesystem to which pathPtr
+defined. The appropriate function for the filesystem to which \fIpathPtr\fR
belongs will be called. If that filesystem does not implement this
function (most virtual filesystems will not, because of OS limitations
in dynamically loading binary code), Tcl will attempt to copy the file
to a temporary directory and load that temporary file.
.PP
Returns a standard Tcl completion code. If an error occurs, an error
-message is left in the interp's result.
+message is left in the \fIinterp\fR's result.
.PP
\fBTcl_FSMatchInDirectory\fR is used by the globbing code to search a
directory for all files which match a given pattern. The appropriate
-function for the filesystem to which pathPtr belongs will be called.
+function for the filesystem to which \fIpathPtr\fR belongs will be called.
.PP
The return value is a standard Tcl result indicating whether an error
-occurred in globbing. Error messages are placed in interp, but good
-results are placed in the resultPtr given.
+occurred in globbing. Error messages are placed in \fIinterp\fR, but good
+results are placed in the \fIresultPtr\fR given.
-Note that the 'glob' code implements recursive patterns internally, so
+Note that the \fBglob\fR code implements recursive patterns internally, so
this function will only ever be passed simple patterns, which can be
matched using the logic of 'string match'. To handle recursion, Tcl
will call this function frequently asking only for directories to be
returned.
.PP
-\fBTcl_FSLink\fR replaces the library version of readlink(), and
+\fBTcl_FSLink\fR replaces the library version of \fBreadlink\fR, and
extends it to support the creation of links. The appropriate function
-for the filesystem to which linkNamePtr belongs will be called.
+for the filesystem to which \fIlinkNamePtr\fR belongs will be called.
.PP
-If the \fItoPtr\fR is NULL, a readlink action is performed. The result
+If the \fItoPtr\fR is NULL, a 'readlink' action is performed. The result
is a Tcl_Obj specifying the contents of the symbolic link given by
\fIlinkNamePtr\fR, or NULL if the link could not be read. The result is owned
by the caller, which should call Tcl_DecrRefCount when the result is no
longer needed. If the \fItoPtr\fR is not NULL, Tcl should create a link
of one of the types passed in in the \fIlinkAction\fR flag. This flag is
-an or'd combination of TCL_CREATE_SYMBOLIC_LINK and TCL_CREATE_HARD_LINK.
+an ORed combination of TCL_CREATE_SYMBOLIC_LINK and TCL_CREATE_HARD_LINK.
Where a choice exists (i.e. more than one flag is passed in), the Tcl
convention is to prefer symbolic links. When a link is successfully
created, the return value should be \fItoPtr\fR (which is therefore
@@ -402,23 +402,23 @@
documentation). If successful, the function
will update the 'atime' and 'mtime' values of the file given.
.PP
-\fBTcl_FSFileAttrsGet\fR implements read access for the hookable 'file
-attributes' subcommand. The appropriate function for the filesystem to
-which pathPtr belongs will be called.
+\fBTcl_FSFileAttrsGet\fR implements read access for the hookable
+\fBfile attributes\fR subcommand. The appropriate function for the
+filesystem to which \fIpathPtr\fR belongs will be called.
.PP
-If the result is TCL_OK, then an object was placed in objPtrRef, which
+If the result is TCL_OK, then an object was placed in \fIobjPtrRef\fR, which
will only be temporarily valid (unless Tcl_IncrRefCount is called).
.PP
-\fBTcl_FSFileAttrsSet\fR implements write access for the hookable 'file
-attributes' subcommand. The appropriate function for the filesystem to
-which pathPtr belongs will be called.
+\fBTcl_FSFileAttrsSet\fR implements write access for the hookable
+\fBfile attributes\fR subcommand. The appropriate function for the
+filesystem to which \fIpathPtr\fR belongs will be called.
.PP
-\fBTcl_FSFileAttrStrings\fR implements part of the hookable 'file attributes'
+\fBTcl_FSFileAttrStrings\fR implements part of the hookable \fBfile attributes\fR
subcommand. The appropriate function for the filesystem to which
-pathPtr belongs will be called.
+\fIpathPtr\fR belongs will be called.
.PP
The called procedure may either return an array of strings, or may
-instead return NULL and place a Tcl list into the given objPtrRef. Tcl
+instead return NULL and place a Tcl list into the given \fIobjPtrRef\fR. Tcl
will take that list and first increment its refCount before using it.
On completion of that use, Tcl will decrement its refCount. Hence if
the list should be disposed of by Tcl when done, it should have a
@@ -426,7 +426,7 @@
filesystem should ensure it retains a refCount on the object.
.PP
\fBTcl_FSAccess\fR checks whether the process would be allowed to read,
-write or test for existence of the file (or other file system object)
+write or test for existence of the file (or other filesystem object)
whose name is pathname. If pathname is a symbolic link on Unix,
then permissions of the file referred by this symbolic link are
tested.
@@ -467,15 +467,15 @@
previously closed, the act of creating the new channel also assigns it as a
replacement for the standard channel.
.PP
-\fBTcl_FSGetCwd\fR replaces the library version of getcwd().
+\fBTcl_FSGetCwd\fR replaces the library version of \fBgetcwd\fR.
.PP
It returns the Tcl library's current working directory. This may be
different to the native platform's working directory, in the case for
-which the cwd is not in the native filesystem.
+which the \fBcwd\fR is not in the native filesystem.
.PP
The result is a pointer to a Tcl_Obj specifying the current directory,
or NULL if the current directory could not be determined. If NULL is
-returned, an error message is left in the interp's result.
+returned, an error message is left in the \fIinterp\fR's result.
The result already has its refCount incremented for the caller. When
it is no longer needed, that refCount should be decremented. This is
@@ -483,18 +483,18 @@
this and related functions, while ensuring the results are always
valid.
.PP
-\fBTcl_FSChdir\fR replaces the library version of chdir(). The path is
+\fBTcl_FSChdir\fR replaces the library version of \fBchdir\fR. The path is
normalized and then passed to the filesystem which claims it. If that
filesystem does not implement this function, Tcl will fallback to a
combination of stat and access to check whether the directory exists
and has appropriate permissions.
.PP
-For results, see chdir() documentation. If successful, we keep a
-record of the successful path in cwdPathPtr for subsequent calls to
-getcwd.
+For results, see \fBchdir\fR documentation. If successful, we keep a
+record of the successful path in \fIcwdPathPtr\fR for subsequent calls to
+\fBgetcwd\fR.
.PP
\fBTcl_FSPathSeparator\fR returns the separator character to be used for
-most specific element of the path specified by pathPtr (i.e. the last
+most specific element of the path specified by \fIpathPtr\fR (i.e. the last
part of the path).
.PP
The separator is returned as a Tcl_Obj containing a string of length
@@ -513,7 +513,7 @@
refCount to it before freeing the list.
.PP
Returns object, typically with refCount of zero (but it could be shared
-under some conditions) , containing the joined path. The caller must
+under some conditions), containing the joined path. The caller must
add a refCount to the object before using it. In particular, the
returned object could be an element of the given list, so freeing the
list might free the object prematurely if no refCount has been taken.
@@ -524,7 +524,7 @@
and returns a Tcl List object containing each segment of that path as
an element.
.PP
-Returns list object with refCount of zero. If the passed in lenPtr is
+Returns list object with refCount of zero. If the passed in \fIlenPtr\fR is
non-NULL, we use it to return the number of elements in the returned
list.
.PP
@@ -556,7 +556,7 @@
Returns object, typically with refCount of zero (but it could be shared
under some conditions), containing the joined path. The caller must
add a refCount to the object before using it. If any of the objects
-passed into this function (pathPtr or path elements) have a refCount
+passed into this function (\fIpathPtr\fR or path elements) have a refCount
of zero, they will be freed when this function returns.
.PP
\fBTcl_FSConvertToPathType\fR tries to convert the given Tcl_Obj to a valid
@@ -596,13 +596,13 @@
\fBTcl_FSGetTranslatedStringPath\fR does the same as
\fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL.
The string returned is dynamically allocated and owned by the caller,
-which must store it or call ckfree to ensure it is freed. Again,
+which must store it or call \fBckfree\fR to ensure it is freed. Again,
\fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually
better functions to use for most purposes.
.PP
\fBTcl_FSNewNativePath\fR performs something like that reverse of the
usual obj->path->nativerep conversions. If some code retrieves a path
-in native form (from, e.g. readlink or a native dialog), and that path
+in native form (from, e.g. \fBreadlink\fR or a native dialog), and that path
is to be used at the Tcl level, then calling this function is an
efficient way of creating the appropriate path object type.
.PP
@@ -742,13 +742,13 @@
efficient emulations it can fall back on). It is important to note
that, in the current version of Tcl, most of these fallbacks are only
used to handle commands initiated in Tcl, not in C. What this means is,
-that if a 'file rename' command is issued in Tcl, and the relevant
+that if a \fBfile rename\fR command is issued in Tcl, and the relevant
filesystem(s) do not implement their \fITcl_FSRenameFileProc\fR, Tcl's
core will instead fallback on a combination of other filesystem
functions (it will use \fITcl_FSCopyFileProc\fR followed by
\fITcl_FSDeleteFileProc\fR, and if \fITcl_FSCopyFileProc\fR is not
implemented there is a further fallback). However, if a
-\fITcl_FSRenameFile\fR command is issued at the C level, no such
+\fITcl_FSRenameFileProc\fR command is issued at the C level, no such
fallbacks occur. This is true except for the last four entries in the
filesystem table (lstat, load, getcwd and chdir)
for which fallbacks do in fact occur at the C level.
@@ -780,7 +780,7 @@
&VfsOpenFileChannel,
&VfsMatchInDirectory,
&VfsUtime,
- /* We choose not to support symbolic links inside our vfs's */
+ /* We choose not to support symbolic links inside our VFSs */
NULL,
&VfsListVolumes,
&VfsFileAttrStrings,
@@ -813,7 +813,7 @@
.PP
The \fItypeName\fR field contains a null-terminated string that
identifies the type of the filesystem implemented, e.g.
-\fBnative\fR or \fBzip\fR or \fBvfs\fR.
+``native'' or ``zip'' or ``vfs''.
.PP
.SH "STRUCTURE LENGTH"
.PP
@@ -838,7 +838,7 @@
functions with a path for which this function has returned \fBTCL_OK\fR.
If the path does not belong, -1 should be returned (the behaviour of Tcl
for any other return value is not defined). If \fBTCL_OK\fR is returned,
-then the optional \fBclientDataPtr\fR output parameter can be used to
+then the optional \fIclientDataPtr\fR output parameter can be used to
return an internal (filesystem specific) representation of the path,
which will be cached inside the path object, and may be retrieved
efficiently by the other filesystem functions. Tcl will simultaneously
@@ -908,9 +908,9 @@
link, it should not be converted into the object it points to (but
its case or other aspects should be made unique). All other path
components should be converted from symbolic links. This one
-exception is required to agree with Tcl's semantics with 'file
-delete', 'file rename', 'file copy' operating on symbolic links.
-This function may be called with 'nextCheckpoint' either
+exception is required to agree with Tcl's semantics with \fBfile delete\fR,
+\fBfile rename\fR, \fBfile copy\fR operating on symbolic links.
+This function may be called with \fInextCheckpoint\fR either
at the beginning of the path (i.e. zero), at the end of the path, or
at any intermediate file separator in the path. It will never
point to any other arbitrary position in the path. In the last of
@@ -964,7 +964,7 @@
.CE
.SH STATPROC
.PP
-Function to process a \fBTcl_FSStat()\fR call. Must be implemented for any
+Function to process a \fBTcl_FSStat\fR call. Must be implemented for any
reasonable filesystem, since many Tcl level commands depend crucially
upon it (e.g. \fBfile atime\fR, \fBfile isdirectory\fR, \fBfile size\fR,
\fBglob\fR).
@@ -990,7 +990,7 @@
data. Otherwise, -1 is returned, and no stat info is given.
.SH ACCESSPROC
.PP
-Function to process a \fBTcl_FSAccess()\fR call. Must be implemented for
+Function to process a \fBTcl_FSAccess\fR call. Must be implemented for
any reasonable filesystem, since many Tcl level commands depend crucially
upon it (e.g. \fBfile exists\fR, \fBfile readable\fR).
.PP
@@ -1001,8 +1001,8 @@
.CE
.PP
The \fBTcl_FSAccessProc\fR checks whether the process would be allowed
-to read, write or test for existence of the file (or other file system
-object) whose name is pathname. If pathname is a symbolic link, then
+to read, write or test for existence of the file (or other filesystem
+object) whose name is in \fIpathPtr\fR. If file is a symbolic link, then
permissions of the file referred by this symbolic link should be tested.
.PP
On success (all requested permissions granted), zero is returned. On
@@ -1011,7 +1011,7 @@
.PP
.SH OPENFILECHANNELPROC
.PP
-Function to process a \fBTcl_FSOpenFileChannel()\fR call. Must be
+Function to process a \fBTcl_FSOpenFileChannel\fR call. Must be
implemented for any reasonable filesystem, since any operations
which require open or accessing a file's contents will use it
(e.g. \fBopen\fR, \fBencoding\fR, and many Tk commands).
@@ -1044,7 +1044,7 @@
as a replacement for the standard channel.
.SH MATCHINDIRECTORYPROC
.PP
-Function to process a \fBTcl_FSMatchInDirectory()\fR call. If not
+Function to process a \fBTcl_FSMatchInDirectory\fR call. If not
implemented, then glob and recursive copy functionality will be lacking
in the filesystem (and this may impact commands like 'encoding names'
which use glob functionality internally).
@@ -1071,7 +1071,7 @@
not, so code should be flexible to both possibilities.
.PP
The return value is a standard Tcl result indicating whether an error
-occurred in the matching process. Error messages are placed in interp,
+occurred in the matching process. Error messages are placed in \fIinterp\fR,
but on a TCL_OK result, the interpreter should not be modified, but
rather results should be added to the \fIresult\fR object given
(which can be assumed to be a valid Tcl list). The matches added
@@ -1095,9 +1095,9 @@
to have seamless transitions between from one filesystem to another.
.SH UTIMEPROC
.PP
-Function to process a \fBTcl_FSUtime()\fR call. Required to allow setting
-(not reading) of times with 'file mtime', 'file atime' and the
-open-r/open-w/fcopy implementation of 'file copy'.
+Function to process a \fBTcl_FSUtime\fR call. Required to allow setting
+(not reading) of times with \fBfile mtime\fR, \fBfile atime\fR and the
+open-r/open-w/fcopy implementation of \fBfile copy\fR.
.PP
.CS
typedef int Tcl_FSUtimeProc(
@@ -1109,10 +1109,10 @@
should be changed to the values given in the \fItval\fR structure.
.PP
The return value should be 0 on success and -1 on an error, as
-with the system utime().
+with the system \fButime\fR.
.SH LINKPROC
.PP
-Function to process a \fBTcl_FSLink()\fR call. Should be implemented
+Function to process a \fBTcl_FSLink\fR call. Should be implemented
only if the filesystem supports links, and may otherwise be NULL.
.PP
.CS
@@ -1138,7 +1138,7 @@
.PP
Function to list any filesystem volumes added by this filesystem.
Should be implemented only if the filesystem adds volumes at the head
-of the filesystem, so that they can be returned by 'file volumes'.
+of the filesystem, so that they can be returned by \fBfile volumes\fR.
.PP
.CS
typedef Tcl_Obj* Tcl_FSListVolumesProc(void);
@@ -1174,7 +1174,7 @@
.CE
.PP
The called function may either return an array of strings, or may
-instead return NULL and place a Tcl list into the given objPtrRef. Tcl
+instead return NULL and place a Tcl list into the given \fIobjPtrRef\fR. Tcl
will take that list and first increment its refCount before using it.
On completion of that use, Tcl will decrement its refCount. Hence if
the list should be disposed of by Tcl when done, it should have a
@@ -1182,8 +1182,7 @@
filesystem should ensure it retains a refCount on the object.
.SH FILEATTRSGETPROC
.PP
-Function to process a \fBTcl_FSFileAttrsGet()\fR call, used by 'file
-attributes'.
+Function to process a \fBTcl_FSFileAttrsGet\fR call, used by \fBfile attributes\fR.
.PP
.CS
typedef int Tcl_FSFileAttrsGetProc(
@@ -1195,14 +1194,14 @@
.PP
Returns a standard Tcl return code. The attribute value retrieved,
which corresponds to the \fIindex\fR'th element in the list returned by
-the Tcl_FSFileAttrStringsProc, is a Tcl_Obj placed in objPtrRef (if
+the Tcl_FSFileAttrStringsProc, is a Tcl_Obj placed in \fIobjPtrRef\fR (if
TCL_OK was returned) and is likely to have a refCount of zero. Either
way we must either store it somewhere (e.g. the Tcl result), or
Incr/Decr its refCount to ensure it is properly freed.
.SH FILEATTRSSETPROC
.PP
-Function to process a \fBTcl_FSFileAttrsSet()\fR call, used by 'file
-attributes'. If the filesystem is read-only, there is no need
+Function to process a \fBTcl_FSFileAttrsSet\fR call, used by
+\fBfile attributes\fR. If the filesystem is read-only, there is no need
to implement this.
.PP
.CS
@@ -1217,7 +1216,7 @@
the Tcl_FSFileAttrStringsProc should be set to the \fIobjPtr\fR given.
.SH CREATEDIRECTORYPROC
.PP
-Function to process a \fBTcl_FSCreateDirectory()\fR call. Should be
+Function to process a \fBTcl_FSCreateDirectory\fR call. Should be
implemented unless the FS is read-only.
.PP
.CS
@@ -1231,7 +1230,7 @@
\fIpathPtr\fR.
.SH REMOVEDIRECTORYPROC
.PP
-Function to process a 'Tcl_FSRemoveDirectory()' call. Should be
+Function to process a \fBTcl_FSRemoveDirectory\fR call. Should be
implemented unless the FS is read-only.
.PP
.CS
@@ -1246,12 +1245,12 @@
\fIpathPtr\fR should have been removed from the filesystem. If the
\fIrecursive\fR flag is given, then a non-empty directory should be
deleted without error. If this flag is not given, then and the
-directory is non-empty a posix EEXIST error should be signalled. If an
+directory is non-empty a POSIX EEXIST error should be signalled. If an
error does occur, the name of the file or directory which caused the
error should be placed in \fIerrorPtr\fR.
.SH DELETEFILEPROC
.PP
-Function to process a \fBTcl_FSDeleteFile()\fR call. Should be implemented
+Function to process a \fBTcl_FSDeleteFile\fR call. Should be implemented
unless the FS is read-only.
.PP
.CS
@@ -1269,7 +1268,7 @@
.PP
.SH LSTATPROC
.PP
-Function to process a \fBTcl_FSLstat()\fR call. If not implemented, Tcl
+Function to process a \fBTcl_FSLstat\fR call. If not implemented, Tcl
will attempt to use the \fIstatProc\fR defined above instead. Therefore
it need only be implemented if a filesystem can differentiate between
\fBstat\fR and \fBlstat\fR calls.
@@ -1287,8 +1286,8 @@
.PP
.SH COPYFILEPROC
.PP
-Function to process a \fBTcl_FSCopyFile()\fR call. If not implemented Tcl
-will fall back on open-r, open-w and fcopy as a copying mechanism.
+Function to process a \fBTcl_FSCopyFile\fR call. If not implemented Tcl
+will fall back on \fBopen-r, open-w\fR and \fBfcopy\fR as a copying mechanism.
Therefore it need only be implemented if the filesystem can perform
that action more efficiently.
.PP
@@ -1302,17 +1301,17 @@
occurred in the copying process. Note that, \fIdestPathPtr\fR is the
name of the file which should become the copy of \fIsrcPathPtr\fR. It
is never the name of a directory into which \fIsrcPathPtr\fR could be
-copied (i.e. the function is much simpler than the Tcl level 'file
-copy' subcommand). Note that,
+copied (i.e. the function is much simpler than the Tcl level \fBfile copy\fR
+subcommand). Note that,
if the filesystem supports symbolic links, Tcl will always call this
-function and not Tcl_FSCopyDirectoryProc when needed to copy them
+function and not \fIcopyDirectoryProc\fR when needed to copy them
(even if they are symbolic links to directories). Finally, if the
-filesystem determines it cannot support the file copy action,
+filesystem determines it cannot support the \fBfile copy\fR action,
calling \fBTcl_SetErrno(EXDEV)\fR and returning a non
TCL_OK result will tell Tcl to use its standard fallback mechanisms.
.SH RENAMEFILEPROC
.PP
-Function to process a \fBTcl_FSRenameFile()\fR call. If not implemented,
+Function to process a \fBTcl_FSRenameFile\fR call. If not implemented,
Tcl will fall back on a copy and delete mechanism. Therefore it need
only be implemented if the filesystem can perform that action more
efficiently.
@@ -1325,13 +1324,13 @@
.PP
The return value is a standard Tcl result indicating whether an error
occurred in the renaming process. If the
-filesystem determines it cannot support the file rename action,
+filesystem determines it cannot support the \fBfile rename\fR action,
calling \fBTcl_SetErrno(EXDEV)\fR and returning a non
TCL_OK result will tell Tcl to use its standard fallback mechanisms.
.SH COPYDIRECTORYPROC
.PP
-Function to process a \fBTcl_FSCopyDirectory()\fR call. If not
-implemented, Tcl will fall back on a recursive create-dir, file copy
+Function to process a \fBTcl_FSCopyDirectory\fR call. If not
+implemented, Tcl will fall back on a recursive create-dir, file-copy
mechanism. Therefore it need only be implemented if the filesystem can
perform that action more efficiently.
.PP
@@ -1349,14 +1348,14 @@
directory-name which should become the mirror-image of
\fIsrcPathPtr\fR. It is not the name of a directory into which
\fIsrcPathPtr\fR should be copied (i.e. the function is much simpler
-than the Tcl level 'file copy' subcommand). Finally, if the
+than the Tcl level \fBfile copy\fR subcommand). Finally, if the
filesystem determines it cannot support the directory copy action,
calling \fBTcl_SetErrno(EXDEV)\fR and returning a non
TCL_OK result will tell Tcl to use its standard fallback mechanisms.
.SH LOADFILEPROC
.PP
-Function to process a \fBTcl_FSLoadFile()\fR call. If not implemented, Tcl
-will fall back on a copy to native-temp followed by a Tcl_FSLoadFile on
+Function to process a \fBTcl_FSLoadFile\fR call. If not implemented, Tcl
+will fall back on a copy to native-temp followed by a \fBTcl_FSLoadFile\fR on
that temporary copy. Therefore it need only be implemented if the
filesystem can load code directly, or it can be implemented simply to
return TCL_ERROR to disable load functionality in this filesystem
@@ -1371,7 +1370,7 @@
.CE
.PP
Returns a standard Tcl completion code. If an error occurs, an error
-message is left in the interp's result. The function dynamically loads a
+message is left in the \fIinterp\fR's result. The function dynamically loads a
binary code file into memory. On a successful load, the \fIhandlePtr\fR
should be filled with a token for the dynamically loaded file, and the
\fIunloadProcPtr\fR should be filled in with the address of a procedure.
@@ -1381,7 +1380,7 @@
which can be used in the private \fBTclpFindSymbol\fR to access functions
in the new code. Each filesystem is free to define the
\fBTcl_LoadHandle\fR as it requires. Finally, if the
-filesystem determines it cannot support the file load action,
+filesystem determines it cannot support the file-load action,
calling \fBTcl_SetErrno(EXDEV)\fR and returning a non
TCL_OK result will tell Tcl to use its standard fallback mechanisms.
.SH UNLOADFILEPROC
@@ -1396,9 +1395,9 @@
.CE
.SH GETCWDPROC
.PP
-Function to process a \fBTcl_FSGetCwd()\fR call. Most filesystems need not
-implement this. It will usually only be called once, if 'getcwd' is
-called before 'chdir'. May be NULL.
+Function to process a \fBTcl_FSGetCwd\fR call. Most filesystems need not
+implement this. It will usually only be called once, if \fBgetcwd\fR is
+called before \fBchdir\fR. May be NULL.
.PP
.CS
typedef Tcl_Obj* Tcl_FSGetCwdProc(
@@ -1410,18 +1409,18 @@
function should return that cwd as the result, or NULL if the current
directory could not be determined (e.g. the user does not have
appropriate permissions on the cwd directory). If NULL is returned, an
-error message is left in the interp's result.
+error message is left in the \fIinterp\fR's result.
.PP
.SH CHDIRPROC
.PP
-Function to process a \fBTcl_FSChdir()\fR call. If filesystems do not
+Function to process a \fBTcl_FSChdir\fR call. If filesystems do not
implement this, it will be emulated by a series of directory access
checks. Otherwise, virtual filesystems which do implement it need only
-respond with a positive return result if the dirName is a valid,
+respond with a positive return result if the \fIpathPtr\fR is a valid,
accessible directory in their filesystem. They need not remember the
-result, since that will be automatically remembered for use by GetCwd.
+result, since that will be automatically remembered for use by \fBgetcwd\fR.
Real filesystems should carry out the correct action (i.e. call the
-correct system 'chdir' api).
+correct system \fBchdir\fR API).
.PP
.CS
typedef int Tcl_FSChdirProc(
