@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, 2009, 2010, 2011
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/files
@end smallexample
@noindent
-(See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
+(See @code{switch-to-buffer} in @ref{Switching Buffers}.)
If @var{wildcards} is non-@code{nil}, which is always true in an
interactive call, then @code{find-file} expands wildcard characters in
@var{filename} in the minibuffer.
@end deffn
+@deffn Command find-file-literally filename
+This command visits @var{filename}, like @code{find-file} does, but it
+does not perform any format conversions (@pxref{Format Conversion}),
+character code conversions (@pxref{Coding Systems}), or end-of-line
+conversions (@pxref{Coding System Basics, End of line conversion}).
+The buffer visiting the file is made unibyte, and its major mode is
+Fundamental mode, regardless of the file name. File local variable
+specifications in the file (@pxref{File Local Variables}) are
+ignored, and automatic decompression and adding a newline at the end
+of the file due to @code{require-final-newline} (@pxref{Saving
+Buffers, require-final-newline}) are also disabled.
+
+Note that if Emacs already has a buffer visiting the same file
+non-literally, it will not visit the same file literally, but instead
+just switch to the existing buffer. If you want to be sure of
+accessing a file's contents literally, you should create a temporary
+buffer and then read the file contents into it using
+@code{insert-file-contents-literally} (@pxref{Reading from Files}).
+@end deffn
+
@defun find-file-noselect filename &optional nowarn rawfile wildcards
This function is the guts of all the file-visiting functions. It
returns a buffer visiting the file @var{filename}. You may make the
@deffn Command find-file-other-window filename &optional wildcards
This command selects a buffer visiting the file @var{filename}, but
-does so in a window other than the selected window. It may use another
-existing window or split a window; see @ref{Displaying Buffers}.
+does so in a window other than the selected window. It may use
+another existing window or split a window; see @ref{Switching
+Buffers}.
When this command is called interactively, it prompts for
@var{filename}.
@var{filename}.
@end deffn
-@deffn Command view-file filename
-This command visits @var{filename} using View mode, returning to the
-previous buffer when you exit View mode. View mode is a minor mode that
-provides commands to skim rapidly through the file, but does not let you
-modify the text. Entering View mode runs the normal hook
-@code{view-mode-hook}. @xref{Hooks}.
-
-When @code{view-file} is called interactively, it prompts for
-@var{filename}.
-@end deffn
-
@defopt find-file-wildcards
If this variable is non-@code{nil}, then the various @code{find-file}
commands check for wildcard characters and visit all the files that
used, and in many cases only some of the functions are called.
@end defvar
+@defvar find-file-literally
+This buffer-local variable, if set to a non-@code{nil} value, makes
+@code{save-buffer} behave as if the buffer were visiting its file
+literally, i.e. without conversions of any kind. The command
+@code{find-file-literally} sets this variable's local value, but other
+equivalent functions and commands can do that as well, e.g.@: to avoid
+automatic addition of a newline at the end of the file. This variable
+is permanent local, so it is unaffected by changes of major modes.
+@end defvar
+
@node Subroutines of Visiting
@comment node-name, next, previous, up
@subsection Subroutines of Visiting
@defun file-truename filename
The function @code{file-truename} returns the truename of the file
-@var{filename}. The argument must be an absolute file name.
+@var{filename}. If the argument is not an absolute file name,
+this function first expands it against @code{default-directory}.
This function does not expand environment variables. Only
@code{substitute-in-file-name} does that. @xref{Definition of
@end group
@group
-(set-file-modes "~/junk/diffs" 438)
+(set-file-modes "~/junk/diffs" #o666)
@result{} nil
@end group
-@group
-(format "%o" 438)
- @result{} "666" ; @r{Convert to octal.}
-@end group
-
@group
% ls -l diffs
-rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
@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 still fits into a 32-bit integer, then the value has the
+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 is wider than 32 bits, the value is of the form
+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 24 bits, @var{middle} the next 24 bits, and @var{low} the low
+the high bits, @var{middle} the middle 24 bits, and @var{low} the low
16 bits.
@item
links.
@end deffn
-@deffn Command delete-file filename
+@cindex trash
+@vindex delete-by-moving-to-trash
+@deffn Command delete-file filename &optional trash
@pindex rm
-This command deletes the file @var{filename}, like the shell command
-@samp{rm @var{filename}}. If the file has multiple names, it continues
-to exist under the other names.
-
-A suitable kind of @code{file-error} error is signaled if the file does
-not exist, or is not deletable. (On Unix and GNU/Linux, a file is
-deletable if its directory is writable.)
-
-If @var{filename} is a symbolic link, @code{delete-file} does not
-replace it with its target, but it does follow symbolic links at all
-levels of parent directories.
+This command deletes the file @var{filename}. If the file has
+multiple names, it continues to exist under the other names. If
+@var{filename} is a symbolic link, @code{delete-file} deletes only the
+symbolic link and not its target (though it does follow symbolic links
+at all levels of parent directories).
+
+A suitable kind of @code{file-error} error is signaled if the file
+does not exist, or is not deletable. (On Unix and GNU/Linux, a file
+is deletable if its directory is writable.)
+
+If the optional argument @var{trash} is non-@code{nil} and the
+variable @code{delete-by-moving-to-trash} is non-@code{nil}, this
+command moves the file into the system Trash instead of deleting it.
+@xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU
+Emacs Manual}. When called interactively, @var{trash} is @code{t} if
+no prefix argument is given, and @code{nil} otherwise.
See also @code{delete-directory} in @ref{Create/Delete Dirs}.
@end deffn
The argument @var{mode} must be an integer. On most systems, only the
low 9 bits of @var{mode} are meaningful. You can use the Lisp construct
-for octal character codes to enter @var{mode}; for example,
+for octal numbers to enter @var{mode}; for example,
@example
-(set-default-file-modes ?\644)
+(set-default-file-modes #o644)
@end example
Saving a modified version of an existing file does not count as creating
not an extension.
@end defun
-@ignore
-Andrew Innes says that this
-
-@c @defvar directory-sep-char
-This variable holds the character that Emacs normally uses to separate
-file name components. The default value is @code{?/}, but on MS-Windows
-you can set it to @code{?\\}; then the functions that transform file names
-use backslashes in their output.
-
-File names using backslashes work as input to Lisp primitives even on
-MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
-value of @code{?/}.
-@end defvar
-@end ignore
@node Relative File Names
@subsection Absolute and Relative File Names
because this is not portable. Always use
@code{file-name-as-directory}.
-@cindex directory name abbreviation
- Directory name abbreviations are useful for directories that are
-normally accessed through symbolic links. Sometimes the users recognize
-primarily the link's name as ``the name'' of the directory, and find it
-annoying to see the directory's ``real'' name. If you define the link
-name as an abbreviation for the ``real'' name, Emacs shows users the
-abbreviation instead.
-
-@defopt directory-abbrev-alist
-The variable @code{directory-abbrev-alist} contains an alist of
-abbreviations to use for file directories. Each element has the form
-@code{(@var{from} . @var{to})}, and says to replace @var{from} with
-@var{to} when it appears in a directory name. The @var{from} string is
-actually a regular expression; it is matched against directory names
-anchored at the first character, so it should start with @samp{\`}, to
-support directory names with embedded newlines (which will defeat
-@samp{^}). The @var{to} string should be an ordinary absolute
-directory name. Do not use @samp{~} to stand for a home directory in
-that string. The function @code{abbreviate-file-name} performs these
-substitutions.
-
-You can set this variable in @file{site-init.el} to describe the
-abbreviations appropriate for your site.
-
-Here's an example, from a system on which file system @file{/home/fsf}
-and so on are normally accessed through symbolic links named @file{/fsf}
-and so on.
-
-@example
-(("\\`/home/fsf" . "/fsf")
- ("\\`/home/gp" . "/gp")
- ("\\`/home/gd" . "/gd"))
-@end example
-@end defopt
-
To convert a directory name to its abbreviation, use this
function:
@defun abbreviate-file-name filename
@anchor{Definition of abbreviate-file-name}
-This function applies abbreviations from @code{directory-abbrev-alist}
-to its argument, and also substitutes @samp{~} for the user's home
-directory if the argument names a file in the home directory or one of
-its subdirectories. (If the home directory is a root directory, it is
-not replaced with @samp{~}, because this does not make the result
-shorter on many systems.) You can use it for directory names and for
-file names, because it recognizes abbreviations even as part of the
-name.
+This function returns an abbreviated form of @var{filename}. It
+applies the abbreviations specified in @code{directory-abbrev-alist}
+(@pxref{File Aliases,,File Aliases, emacs, The GNU Emacs Manual}),
+then substitutes @samp{~} for the user's home directory if the
+argument names a file in the home directory or one of its
+subdirectories. If the home directory is a root directory, it is not
+replaced with @samp{~}, because this does not make the result shorter
+on many systems.
+
+You can use this function for directory names and for file names,
+because it recognizes abbreviations even as part of the name.
@end defun
@node File Name Expansion
@code{mkdir} is an alias for this.
@end deffn
-@deffn Command copy-directory dirname newname &optional keep-time parents
+@deffn Command copy-directory dirname newname &optional keep-time parents copy-contents
This command copies the directory named @var{dirname} to
@var{newname}. If @var{newname} names an existing directory,
@var{dirname} will be copied to a subdirectory there.
It always sets the file modes of the copied files to match the
corresponding original file.
-The third arg @var{keep-time} non-@code{nil} means to preserve the
+The third argument @var{keep-time} non-@code{nil} means to preserve the
modification time of the copied files. A prefix arg makes
@var{keep-time} non-@code{nil}.
-Noninteractively, the last argument @var{parents} says whether to
+The fourth argument @var{parents} says whether to
create parent directories if they don't exist. Interactively,
this happens by default.
+
+The fifth argument @var{copy-contents}, if non-@code{nil}, means to
+copy the contents of @var{dirname} directly into @var{newname} if the
+latter is an existing directory, instead of copying @var{dirname} into
+it as a subdirectory.
@end deffn
-@deffn Command delete-directory dirname &optional recursive
+@cindex trash
+@vindex delete-by-moving-to-trash
+@deffn Command delete-directory dirname &optional recursive trash
This command deletes the directory named @var{dirname}. The function
@code{delete-file} does not work for files that are directories; you
must use @code{delete-directory} for them. If @var{recursive} is
@code{delete-directory} only follows symbolic links at the level of
parent directories.
+
+If the optional argument @var{trash} is non-@code{nil} and the
+variable @code{delete-by-moving-to-trash} is non-@code{nil}, this
+command moves the file into the system Trash instead of deleting it.
+@xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU
+Emacs Manual}. When called interactively, @var{trash} is @code{t} if
+no prefix argument is given, and @code{nil} otherwise.
@end deffn
@node Magic File Names
filenames, that means they are stored on the same file system and can
be accessed locally with respect to each other. This means, for
example, that it is possible to start a remote process accessing both
-files at the same time. Implementors of file handlers need to ensure
+files at the same time. Implementers of file handlers need to ensure
this principle is valid.
@var{identification} specifies which part of the identifier shall be
is a good way to come up with one.
@end defun
+@defopt remote-file-name-inhibit-cache
+Whether to use the remote file-name cache for read access.
+
+File attributes of remote files are cached for better performance. If
+they are changed out of Emacs' control, the cached values become
+invalid, and must be reread.
+
+When set to @code{nil}, cached values are always used. This shall be
+set with care. When set to @code{t}, cached values are never used.
+ALthough this is the safest value, it could result in performance
+degradation.
+
+A compromise is to set it to a positive number. This means that
+cached values are used for that amount of seconds since they were
+cached.
+
+In case a remote file is checked regularly, it might be reasonable to
+let-bind this variable to a value less then the time period between
+two checks. Example:
+
+@example
+(defun display-time-file-nonempty-p (file)
+ (let ((remote-file-name-inhibit-cache (- display-time-interval 5)))
+ (and (file-exists-p file)
+ (< 0 (nth 7 (file-attributes (file-chase-links file)))))))
+@end example
+@end defopt
+
@node Format Conversion
@section File Format Conversion
names or values---because a program that general is probably difficult
to write, and slow. Instead, choose a set of possible data types that
are reasonably flexible, and not too hard to encode.
-
-@ignore
- arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c
-@end ignore
HCoop / bpt / emacs.git / blobdiff