comparison lispref/files.texi @ 24951:7451b1458af1

*** empty log message ***

24950:39bac3b71db1

  In a Lisp program, if you want to look at the contents of a file but
not alter it, the fastest way is to use @code{insert-file-contents} in a
temporary buffer.  Visiting the file is not necessary and takes longer.
@xref{Reading from Files}.

@deffn Command find-file filename
This command selects a buffer visiting the file @var{filename},
using an existing buffer if there is one, and otherwise creating a 
new buffer and reading the file into it.  It also returns that buffer.

The body of the @code{find-file} function is very simple and looks

@end example

@noindent
(See @code{switch-to-buffer} in @ref{Displaying Buffers}.)

When @code{find-file} is called interactively, it prompts for
@var{filename} in the minibuffer.
@end deffn

@defun find-file-noselect filename &optional nowarn rawfile
This function is the guts of all the file-visiting functions.  It finds
or creates a buffer visiting the file @var{filename}, and returns it.
It uses an existing buffer if there is one, and otherwise creates a new
buffer and reads the file into it.  You may make the buffer current or
display it in a window if you wish, but this function does not do so.

When @code{find-file-noselect} uses an existing buffer, it first
verifies that the file has not changed since it was last visited or
saved in that buffer.  If the file has changed, then this function asks
the user whether to reread the changed file.  If the user says

     @result{} #<buffer fstab>
@end group
@end example
@end defun

@deffn Command find-file-other-window filename
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}.

When this command is called interactively, it prompts for
@var{filename}.
@end deffn

@deffn Command find-file-read-only filename
This command selects a buffer visiting the file @var{filename}, like
@code{find-file}, but it marks the buffer as read-only.  @xref{Read Only
Buffers}, for related functions and variables.

When this command is called interactively, it prompts for

@code{view-mode-hook}.  @xref{Hooks}.

When @code{view-file} is called interactively, it prompts for
@var{filename}.
@end deffn

@defvar find-file-hooks
The value of this variable is a list of functions to be called after a
file is visited.  The file's local-variables specification (if any) will
have been processed before the hooks are run.  The buffer visiting the

  When two users edit the same file at the same time, they are likely to
interfere with each other.  Emacs tries to prevent this situation from
arising by recording a @dfn{file lock} when a file is being modified.
Emacs can then detect the first attempt to modify a buffer visiting a
file that is locked by another Emacs job, and ask the user what to do.

  File locks are not completely reliable when multiple machines can
share file systems.  When file locks do not work, it is possible for two
users to make changes simultaneously, but Emacs can still warn the user
who saves second.  Also, the detection of modification of a buffer
visiting a file changed on disk catches some cases of simultaneous
editing; see @ref{Modification Time}.

@defun file-locked-p filename
This function returns @code{nil} if the file @var{filename} is not
locked.  It returns @code{t} if it is locked by this Emacs process, and
it returns the name of the user who has locked it if it is locked by

@end group
@end example
@end defun

@defun lock-buffer &optional filename
  This function locks the file @var{filename}, if the current buffer is
modified.  The argument @var{filename} defaults to the current buffer's
visited file.  Nothing is done if the current buffer is not visiting a
file, or is not modified.
@end defun

@end example
@end defun

@defun file-regular-p filename
This function returns @code{t} if the file @var{filename} exists and is
a regular file (not a directory, symbolic link, named pipe, terminal, or
other I/O device).
@end defun

@node Truenames
@subsection Truenames

@item
The time of last status change as a list of two integers (as above).

@item
The size of the file in bytes.

@item
The file's modes, as a string of ten letters or dashes,
as in @samp{ls -l}.

@end defun

@defun file-name-all-versions file dirname
This function returns a list of all versions of the file named
@var{file} in directory @var{dirname}.
@end defun

@defun insert-directory file switches &optional wildcard full-directory-p
This function inserts (in the current buffer) a directory listing for
directory @var{file}, formatted with @code{ls} according to

24951:7451b1458af1

  In a Lisp program, if you want to look at the contents of a file but
not alter it, the fastest way is to use @code{insert-file-contents} in a
temporary buffer.  Visiting the file is not necessary and takes longer.
@xref{Reading from Files}.

@deffn Command find-file filename &optional wildcards
This command selects a buffer visiting the file @var{filename},
using an existing buffer if there is one, and otherwise creating a 
new buffer and reading the file into it.  It also returns that buffer.

The body of the @code{find-file} function is very simple and looks

@end example

@noindent
(See @code{switch-to-buffer} in @ref{Displaying 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} and visits all the matching files.

When @code{find-file} is called interactively, it prompts for
@var{filename} in the minibuffer.
@end deffn

@defun find-file-noselect filename &optional nowarn rawfile wildcards
This function is the guts of all the file-visiting functions.  It finds
or creates a buffer visiting the file @var{filename}, and returns it.
It uses an existing buffer if there is one, and otherwise creates a new
buffer and reads the file into it.  You may make the buffer current or
display it in a window if you wish, but this function does not do so.

If @var{wildcards} is non-@code{nil}, which is always true in an
interactive call, then @code{find-file-noselect} expands wildcard
characters in @var{filename} and visits all the matching files.

When @code{find-file-noselect} uses an existing buffer, it first
verifies that the file has not changed since it was last visited or
saved in that buffer.  If the file has changed, then this function asks
the user whether to reread the changed file.  If the user says

     @result{} #<buffer fstab>
@end group
@end example
@end defun

@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}.

When this command is called interactively, it prompts for
@var{filename}.
@end deffn

@deffn Command find-file-read-only filename &optional wildcards
This command selects a buffer visiting the file @var{filename}, like
@code{find-file}, but it marks the buffer as read-only.  @xref{Read Only
Buffers}, for related functions and variables.

When this command is called interactively, it prompts for

@code{view-mode-hook}.  @xref{Hooks}.

When @code{view-file} is called interactively, it prompts for
@var{filename}.
@end deffn

@tindex find-file-wildcards
@defvar 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
match them.  If this is @code{nil}, then wildcard characters are
not treated specially.
@end defvar

@defvar find-file-hooks
The value of this variable is a list of functions to be called after a
file is visited.  The file's local-variables specification (if any) will
have been processed before the hooks are run.  The buffer visiting the

  When two users edit the same file at the same time, they are likely to
interfere with each other.  Emacs tries to prevent this situation from
arising by recording a @dfn{file lock} when a file is being modified.
Emacs can then detect the first attempt to modify a buffer visiting a
file that is locked by another Emacs job, and ask the user what to do.
The file lock is really a file, a symbolic link with a special name,
stored in the same directory as the file you are editing.

  When you access files using NFS, there may be a small probability that
you and another user will both lock the same file ``simultaneously''.
If this happens, it is possible for the two users to make changes
simultaneously, but Emacs will still warn the user who saves second.
Also, the detection of modification of a buffer visiting a file changed
on disk catches some cases of simultaneous editing; see
@ref{Modification Time}.

@defun file-locked-p filename
This function returns @code{nil} if the file @var{filename} is not
locked.  It returns @code{t} if it is locked by this Emacs process, and
it returns the name of the user who has locked it if it is locked by

@end group
@end example
@end defun

@defun lock-buffer &optional filename
This function locks the file @var{filename}, if the current buffer is
modified.  The argument @var{filename} defaults to the current buffer's
visited file.  Nothing is done if the current buffer is not visiting a
file, or is not modified.
@end defun

@end example
@end defun

@defun file-regular-p filename
This function returns @code{t} if the file @var{filename} exists and is
a regular file (not a directory, named pipe, terminal, or
other I/O device).
@end defun

@node Truenames
@subsection Truenames

@item
The time of last status change as a list of two integers (as above).

@item
The size of the file in bytes.  If the size is too large to fit in a
Lisp integer, this is a floating point number.

@item
The file's modes, as a string of ten letters or dashes,
as in @samp{ls -l}.

@end defun

@defun file-name-all-versions file dirname
This function returns a list of all versions of the file named
@var{file} in directory @var{dirname}.
@end defun

@tindex file-expand-wildcards
@defun file-expand-wildcards pattern &optional full
This function expands the wildcard pattern @var{pattern}, returning
alist of file names that match it.

If @var{pattern} is written as an absolute relative file name,
the values are absolute also.

If @var{pattern} is written as a relative file name, it is interpreted
relative to the current default directory.  The file names returned are
normally also relative to the current default directory.  However, if
@var{full} is non-@code{nil}, they are absolute.
@end defun

@defun insert-directory file switches &optional wildcard full-directory-p
This function inserts (in the current buffer) a directory listing for
directory @var{file}, formatted with @code{ls} according to