diff options
Diffstat (limited to 'doc/lispref/files.texi')
| -rw-r--r-- | doc/lispref/files.texi | 184 |
1 files changed, 143 insertions, 41 deletions
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 544992d4ba5..cb31ca5a3de 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -41,6 +41,7 @@ to locale @code{system-messages-locale}, and decoded using coding system simultaneous editing by two people. * Information about Files:: Testing existence, accessibility, size of files. * Changing Files:: Renaming files, changing permissions, etc. +* Files and Storage:: Surviving power and media failures * File Names:: Decomposing and expanding file names. * Contents of Directories:: Getting a list of the files in a directory. * Create/Delete Dirs:: Creating and Deleting Directories. @@ -660,6 +661,15 @@ feature is useful for programs that use files for internal purposes, files that the user does not need to know about. @end deffn +@defvar write-region-inhibit-fsync +If this variable's value is @code{nil}, @code{write-region} uses the +@code{fsync} system call after writing a file. Although this slows +Emacs down, it lessens the risk of data loss after power failure. If +the value is @code{t}, Emacs does not use @code{fsync}. The default +value is @code{nil} when Emacs is interactive, and @code{t} when Emacs +runs in batch mode. @xref{Files and Storage}. +@end defvar + @defmac with-temp-file file body@dots{} @anchor{Definition of with-temp-file} The @code{with-temp-file} macro evaluates the @var{body} forms with a @@ -1210,73 +1220,83 @@ the default, but we plan to change that, so you should specify a non-@code{nil} value for @var{id-format} if you use the returned @acronym{UID} or @acronym{GID}. +Accessor functions are provided to access the elements in this list. +The accessors are mentioned along with the descriptions of the +elements below. + The elements of the list, in order, are: @enumerate 0 @item @code{t} for a directory, a string for a symbolic link (the name -linked to), or @code{nil} for a text file. +linked to), or @code{nil} for a text file +(@code{file-attribute-type}). @c Wordy so as to prevent an overfull hbox. --rjc 15mar92 @item -The number of names the file has. Alternate names, also known as hard -links, can be created by using the @code{add-name-to-file} function -(@pxref{Changing Files}). +The number of names the file has (@code{file-attribute-link-number}). +Alternate names, also known as hard links, can be created by using the +@code{add-name-to-file} function (@pxref{Changing Files}). @item -The file's @acronym{UID}, normally as a string. However, if it does -not correspond to a named user, the value is a number. +The file's @acronym{UID}, normally as a string +(@code{file-attribute-user-id}). However, if it does not correspond +to a named user, the value is a number. @item -The file's @acronym{GID}, likewise. +The file's @acronym{GID}, likewise (@code{file-attribute-group-id}). @item -The time of last access, as a list of four integers @code{(@var{sec-high} -@var{sec-low} @var{microsec} @var{picosec})}. (This is similar to the -value of @code{current-time}; see @ref{Time of Day}.) Note that on -some FAT-based filesystems, only the date of last access is recorded, -so this time will always hold the midnight of the day of last access. +The time of last access, as a list of four integers +@code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})} +(@code{file-attribute-access-time}). (This is similar to the value of +@code{current-time}; see @ref{Time of Day}.) Note that on some +FAT-based filesystems, only the date of last access is recorded, so +this time will always hold the midnight of the day of last access. @cindex modification time of file @item -The time of last modification as a list of four integers (as above). -This is the last time when the file's contents were modified. +The time of last modification as a list of four integers (as above) +(@code{file-attribute-modification-time}). This is the last time when +the file's contents were modified. @item -The time of last status change as a list of four integers (as above). -This is the time of the last change to the file's access mode bits, -its owner and group, and other information recorded in the filesystem -for the file, beyond the file's contents. +The time of last status change as a list of four integers (as above) +(@code{file-attribute-status-change-time}). This is the time of the +last change to the file's access mode bits, its owner and group, and +other information recorded in the filesystem for the file, beyond the +file's contents. @item -The size of the file in bytes. This is floating point if the size is -too large to fit in a Lisp integer. +The size of the file in bytes (@code{file-attribute-size}). This is +floating point if the size is too large to fit in a Lisp integer. @item -The file's modes, as a string of ten letters or dashes, -as in @samp{ls -l}. +The file's modes, as a string of ten letters or dashes, as in +@samp{ls -l} (@code{file-attribute-modes}). @item An unspecified value, present for backward compatibility. @item -The file's inode number. If possible, this is an integer. If the -inode number is too large to be represented as an integer in Emacs -Lisp but dividing it by @math{2^{16}} yields a representable integer, -then the value has the +The file's inode number (@code{file-attribute-inode-number}). If +possible, this is an integer. If the inode number is too large to be +represented as an integer in Emacs Lisp but dividing it by +@math{2^{16}} yields a representable integer, then the value has the form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16 -bits. If the inode number is too wide for even that, the value is of the form -@code{(@var{high} @var{middle} . @var{low})}, where @code{high} holds -the high bits, @var{middle} the middle 24 bits, and @var{low} the low -16 bits. +bits. If the inode number is too wide for even that, the value is of +the form @code{(@var{high} @var{middle} . @var{low})}, where +@code{high} holds the high bits, @var{middle} the middle 24 bits, and +@var{low} the low 16 bits. @item -The filesystem number of the device that the file is on. Depending on -the magnitude of the value, this can be either an integer or a cons -cell, in the same manner as the inode number. This element and the -file's inode number together give enough information to distinguish -any two files on the system---no two files can have the same values -for both of these numbers. +The filesystem number of the device that the file is on +@code{file-attribute-device-number}). Depending on the magnitude of +the value, this can be either an integer or a cons cell, in the same +manner as the inode number. This element and the file's inode number +together give enough information to distinguish any two files on the +system---no two files can have the same values for both of these +numbers. @end enumerate For example, here are the file attributes for @file{files.texi}: @@ -1496,10 +1516,15 @@ in @code{exec-path}, and tries all the file-name extensions in @cindex setting modes of files The functions in this section rename, copy, delete, link, and set -the modes (permissions) of files. They all signal a @code{file-error} -error if they fail to perform their function, reporting the -system-dependent error message that describes the reason for the -failure. +the modes (permissions) of files. Typically, they signal a +@code{file-error} error if they fail to perform their function, +reporting the system-dependent error message that describes the reason +for the failure. If they fail because a file is missing, they signal +a @code{file-missing} error instead. + + For performance, the operating system may cache or alias changes +made by these functions instead of writing them immediately to +secondary storage. @xref{Files and Storage}. In the functions that have an argument @var{newname}, if a file by the name of @var{newname} already exists, the actions taken depend on the @@ -1799,6 +1824,28 @@ The function returns @code{t} if it successfully sets the ACL of @var{filename}, @code{nil} otherwise. @end defun +@node Files and Storage +@section Files and Secondary Storage +@cindex secondary storage + +After Emacs changes a file, there are two reasons the changes might +not survive later failures of power or media, both having to do with +efficiency. First, the operating system might alias written data with +data already stored elsewhere on secondary storage until one file or +the other is later modified; this will lose both files if the only +copy on secondary storage is lost due to media failure. Second, the +operating system might not write data to secondary storage +immediately, which will lose the data if power is lost. + +@findex write-region +Although both sorts of failures can largely be avoided by a suitably +configured file system, such systems are typically more expensive or +less efficient. In more-typical systems, to survive media failure you +can copy the file to a different device, and to survive a power +failure you can use the @code{write-region} function with the +@code{write-region-inhibit-fsync} variable set to @code{nil}. +@xref{Writing to Files}. + @node File Names @section File Names @cindex file names @@ -2445,6 +2492,50 @@ condition, between the @code{make-temp-name} call and the creation of the file, which in some cases may cause a security hole. @end defun +Sometimes, it is necessary to create a temporary file on a remote host +or a mounted directory. The following two functions support this. + +@defun make-nearby-temp-file prefix &optional dir-flag suffix +This function is similar to @code{make-temp-file}, but it creates a +temporary file as close as possible to @code{default-directory}. If +@var{prefix} is a relative file name, and @code{default-directory} is +a remote file name or located on a mounted file systems, the temporary +file is created in the directory returned by the function +@code{temporary-file-directory}. Otherwise, the function +@code{make-temp-file} is used. @var{prefix}, @var{dir-flag} and +@var{suffix} have the same meaning as in @code{make-temp-file}. + +@example +@group +(let ((default-directory "/ssh:remotehost:")) + (make-nearby-temp-file "foo")) + @result{} "/ssh:remotehost:/tmp/foo232J6v" +@end group +@end example +@end defun + +@defun temporary-file-directory +The directory for writing temporary files via +@code{make-nearby-temp-file}. In case of a remote +@code{default-directory}, this is a directory for temporary files on +that remote host. If such a directory does not exist, or +@code{default-directory} ought to be located on a mounted file system +(see @code{mounted-file-systems}), the function returns +@code{default-directory}. For a non-remote and non-mounted +@code{default-directory}, the value of the variable +@code{temporary-file-directory} is returned. +@end defun + +In order to extract the local part of the path name from a temporary +file, the following code could be used: + +@example +@group +(let ((tmpfile (make-nearby-temp-file "foo"))) + (or (file-remote-p tmpfile 'localname) tmpfile)) +@end group +@end example + @node File Name Completion @subsection File Name Completion @cindex file name completion subroutines @@ -2780,6 +2871,9 @@ This command deletes the directory named @var{dirname}. The function must use @code{delete-directory} for them. If @var{recursive} is @code{nil}, and the directory contains any files, @code{delete-directory} signals an error. +If recursive is non-@code{nil}, there is no error merely because the +directory or its files are deleted by some other process before +@code{delete-directory} gets to them. @code{delete-directory} only follows symbolic links at the level of parent directories. @@ -2908,6 +3002,7 @@ first, before handlers for jobs such as remote file access. @code{make-auto-save-file-name}, @code{make-directory}, @code{make-directory-internal}, +@code{make-nearby-temp-file}, @code{make-symbolic-link},@* @code{process-file}, @code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, @@ -2915,6 +3010,7 @@ first, before handlers for jobs such as remote file access. @code{set-visited-file-modtime}, @code{shell-command}, @code{start-file-process}, @code{substitute-in-file-name},@* +@code{temporary-file-directory}, @code{unhandled-file-name-directory}, @code{vc-registered}, @code{verify-visited-file-modtime},@* @@ -3243,7 +3339,9 @@ end position. One responsibility of @var{from-fn} is to make sure that the beginning of the file no longer matches @var{regexp}. Otherwise it is likely to -get called again. +get called again. Also, @var{from-fn} must not involve buffers or +files other than the one being decoded, otherwise the internal buffer +used for formatting might be overwritten. @item to-fn A shell command or function to encode data in this format---that is, to @@ -3274,6 +3372,10 @@ file, it intermixes the specified annotations at the corresponding positions. All this takes place without modifying the buffer. @end itemize +@var{to-fn} must not involve buffers or files other than the one being +encoded, otherwise the internal buffer used for formatting might be +overwritten. + @item modify A flag, @code{t} if the encoding function modifies the buffer, and @code{nil} if it works by returning a list of annotations. |