X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/61331bf33b28709201836b1950815673e554efa7..97d8273fa2687731d652687cf6b4c7c48dd0661a:/doc/lispref/files.texi diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index c7567e039e..5b171f4d1c 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. +@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/files @node Files, Backups and Auto-Saving, Documentation, Top @@ -500,7 +500,10 @@ the list @code{after-insert-file-functions}. @xref{Format Conversion}. Normally, one of the functions in the @code{after-insert-file-functions} list determines the coding system (@pxref{Coding Systems}) used for decoding the file's contents, -including end-of-line conversion. +including end-of-line conversion. However, if the file contains null +bytes, it is by default visited without any code conversions; see +@ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to +control this behavior. If @var{visit} is non-@code{nil}, this function additionally marks the buffer as unmodified and sets up various fields in the buffer so that it @@ -1266,6 +1269,17 @@ is on file system number -32252. @end table @end defun +@cindex MS-DOS and file modes +@cindex file modes and MS-DOS + On MS-DOS, there is no such thing as an ``executable'' file mode bit. +So Emacs considers a file executable if its name ends in one of the +standard executable extensions, such as @file{.com}, @file{.bat}, +@file{.exe}, and some others. Files that begin with the Unix-standard +@samp{#!} signature, such as shell and Perl scripts, are also considered +as executable files. This is reflected in the values returned by +@code{file-modes} and @code{file-attributes}. Directories are also +reported with executable bit set, for compatibility with Unix. + @node Locating Files @subsection How to Locate Files in Standard Places @cindex locate file in path @@ -1555,7 +1569,8 @@ This subroutine converts a symbolic specification of file mode bits in @var{modes} into the equivalent numeric value. If the symbolic specification is based on an existing file, that file's mode bits are taken from the optional argument @var{base-modes}; if that argument is -omitted or nil, it defaults to zero, i.e.@: no access rights at all. +omitted or @code{nil}, it defaults to zero, i.e.@: no access rights at +all. @end defun @defun set-file-times filename &optional time @@ -1566,17 +1581,6 @@ time and must be in the format returned by @code{current-time} (@pxref{Time of Day}). @end defun -@cindex MS-DOS and file modes -@cindex file modes and MS-DOS - On MS-DOS, there is no such thing as an ``executable'' file mode bit. -So Emacs considers a file executable if its name ends in one of the -standard executable extensions, such as @file{.com}, @file{.bat}, -@file{.exe}, and some others. Files that begin with the Unix-standard -@samp{#!} signature, such as shell and Perl scripts, are also considered -as executable files. This is reflected in the values returned by -@code{file-modes} and @code{file-attributes}. Directories are also -reported with executable bit set, for compatibility with Unix. - @node File Names @section File Names @cindex file names @@ -1701,8 +1705,8 @@ return value, but backup version numbers are kept. This function returns @var{filename}'s final ``extension,'' if any, after applying @code{file-name-sans-versions} to remove any version/backup part. The extension, in a file name, is the part that -starts with the last @samp{.} in the last name component (minus -any version/backup part). +follows the last @samp{.} in the last name component (minus any +version/backup part). This function returns @code{nil} for extensionless file names such as @file{foo}. It returns @code{""} for null extensions, as in @@ -2487,11 +2491,14 @@ files that are directories. For example, you cannot delete a directory with @code{delete-file}. These special functions exist to create and delete directories. +@findex mkdir @defun make-directory dirname &optional parents This function creates a directory named @var{dirname}. If @var{parents} is non-@code{nil}, as is always the case in an interactive call, that means to create the parent directories first, if they don't already exist. + +@code{mkdir} is an alias for this fuction. @end defun @defun delete-directory dirname @@ -2605,7 +2612,7 @@ first, before handlers for jobs such as remote file access. @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, @code{find-backup-file-name}, -@code{find-file-noselect},@* +@c Not sure why it was here: @code{find-file-noselect},@* @code{get-file-buffer}, @code{insert-directory}, @code{insert-file-contents},@* @@ -2652,7 +2659,7 @@ first, before handlers for jobs such as remote file access. @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, @code{find-backup-file-name}, -@code{find-file-noselect}, +@c Not sure why it was here: @code{find-file-noselect}, @code{get-file-buffer}, @code{insert-directory}, @code{insert-file-contents}, @@ -2801,12 +2808,12 @@ making connections when they don't exist. @end defun @defun unhandled-file-name-directory filename -This function returns the name of a directory that is not magic. -It uses the directory part of @var{filename} if that is not magic. -For a magic file name, it invokes the file name handler, which -therefore decides what value to return. If @var{filename} is not -accessible from a local process, then the file name handler should -indicate it by returning nil. +This function returns the name of a directory that is not magic. It +uses the directory part of @var{filename} if that is not magic. For a +magic file name, it invokes the file name handler, which therefore +decides what value to return. If @var{filename} is not accessible +from a local process, then the file name handler should indicate it by +returning @code{nil}. This is useful for running a subprocess; every subprocess must have a non-magic directory to serve as its current directory, and this function @@ -2877,7 +2884,7 @@ This list contains one format definition for each defined file format. Each format definition is a list of this form: @example -(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn}) +(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn} @var{preserve}) @end example @end defvar @@ -2950,6 +2957,10 @@ A flag, @code{t} if the encoding function modifies the buffer, and A minor-mode function to call after visiting a file converted from this format. The function is called with one argument, the integer 1; that tells a minor-mode function to enable the mode. + +@item preserve +A flag, @code{t} if @code{format-write-file} should not remove this format +from @code{buffer-file-format}. @end table The function @code{insert-file-contents} automatically recognizes file @@ -2977,13 +2988,17 @@ encoding functions for the formats listed in @code{buffer-file-format}, in the order of appearance in the list. @deffn Command format-write-file file format &optional confirm -This command writes the current buffer contents into the file -@var{file} in format @var{format}, and makes that format the default -for future saves of the buffer. The argument @var{format} is a list -of format names. Except for the @var{format} argument, this command -is similar to @code{write-file}. In particular, @var{confirm} has the -same meaning and interactive treatment as the corresponding argument -to @code{write-file}. @xref{Definition of write-file}. +This command writes the current buffer contents into the file @var{file} +in a format based on @var{format}, which is a list of format names. It +constructs the actual format starting from @var{format}, then appending +any elements from the value of @code{buffer-file-format} with a non-nil +@var{preserve} flag (see above), if they are not already present in +@var{format}. It then updates @code{buffer-file-format} with this +format, making it the default for future saves. Except for the +@var{format} argument, this command is similar to @code{write-file}. In +particular, @var{confirm} has the same meaning and interactive treatment +as the corresponding argument to @code{write-file}. @xref{Definition of +write-file}. @end deffn @deffn Command format-find-file file format @@ -3058,18 +3073,17 @@ place without modifying the buffer. @c ??? for `write-region-annotate-functions', below? --ttn In contrast, when reading, the annotations intermixed with the text -are handled immediately. @code{insert-file-contents} sets point to the -beginning of some text to be converted, then calls the conversion +are handled immediately. @code{insert-file-contents} sets point to +the beginning of some text to be converted, then calls the conversion functions with the length of that text. These functions should always -return with point at the beginning of the inserted text. This approach -makes sense for reading because annotations removed by the first -converter can't be mistakenly processed by a later converter. - - Each conversion function should scan for the annotations it -recognizes, remove the annotation, modify the buffer text (to set a text -property, for example), and return the updated length of the text, as it -stands after those changes. The value returned by one function becomes -the argument to the next function. +return with point at the beginning of the inserted text. This +approach makes sense for reading because annotations removed by the +first converter can't be mistakenly processed by a later converter. +Each conversion function should scan for the annotations it +recognizes, remove the annotation, modify the buffer text (to set a +text property, for example), and return the updated length of the +text, as it stands after those changes. The value returned by one +function becomes the argument to the next function. @defvar write-region-annotate-functions A list of functions for @code{write-region} to call. Each function in @@ -3077,13 +3091,30 @@ the list is called with two arguments: the start and end of the region to be written. These functions should not alter the contents of the buffer. Instead, they should return annotations. -@c ??? Following adapted from comment in `build_annotations' (fileio.c). -@c ??? Perhaps this is intended for internal use only? -@c ??? Someone who understands this, please reword it. --ttn -As a special case, if a function returns with a different buffer -current, Emacs takes it to mean the current buffer contains altered text -to be output, and discards all previous annotations because they should -have been dealt with by this function. +As a special case, a function may return with a different buffer +current. Emacs takes this to mean that the current buffer contains +altered text to be output. It therefore changes the @var{start} and +@var{end} arguments of the @code{write-region} call, giving them the +values of @code{point-min} and @code{point-max} in the new buffer, +respectively. It also discards all previous annotations, because they +should have been dealt with by this function. +@end defvar + +@defvar write-region-post-annotation-function +The value of this variable, if non-@code{nil}, should be a function. +This function is called, with no arguments, after @code{write-region} +has completed. + +If any function in @code{write-region-annotate-functions} returns with +a different buffer current, Emacs calls +@code{write-region-post-annotation-function} more than once. Emacs +calls it with the last buffer that was current, and again with the +buffer before that, and so on back to the original buffer. + +Thus, a function in @code{write-region-annotate-functions} can create +a buffer, give this variable the local value of @code{kill-buffer} in +that buffer, set up the buffer with altered text, and make the buffer +current. The buffer will be killed after @code{write-region} is done. @end defvar @defvar after-insert-file-functions