comparison lispref/files.texi @ 90796:4ef881a120fe

Merge from emacs--devo--0 Patches applied: * emacs--devo--0 (patch 675-697) - Update from CVS - Merge from gnus--rel--5.10 - Release ERC 5.2. * gnus--rel--5.10 (patch 211-215) - Update from CVS - Merge from emacs--devo--0 Revision: [e-mail]/emacs--unicode--0--patch-189

90795:b9182b6a90c9

in the list @code{find-file-hook}.
@end defun

@node Saving Buffers
@section Saving Buffers

  When you edit a file in Emacs, you are actually working on a buffer
that is visiting that file---that is, the contents of the file are
copied into the buffer and the copy is what you edit.  Changes to the
buffer do not change the file until you @dfn{save} the buffer, which

Name}).

@node Reading from Files
@comment  node-name,  next,  previous,  up
@section Reading from Files

  You can copy a file from the disk and insert it into a buffer
using the @code{insert-file-contents} function.  Don't use the user-level
command @code{insert-file} in a Lisp program, as that sets the mark.

@ref{Magic File Names}.

@node Writing to Files
@comment  node-name,  next,  previous,  up
@section Writing to Files

  You can write the contents of a buffer, or part of a buffer, directly
to a file on disk using the @code{append-to-file} and
@code{write-region} functions.  Don't use these functions to write to
files that are being visited; that could cause confusion in the

@end defmac

@node File Locks
@section File Locks
@cindex file locks

  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.  (File locks are not implemented on Microsoft systems.)

for its usual definition is in @file{userlock.el}.
@end defun

@node Information about Files
@section Information about Files

  The functions described in this section all operate on strings that
designate file names.  With a few exceptions, all the functions have
names that begin with the word @samp{file}.  These functions all
return information about actual files or directories, so their

the second has the low 16 bits.  (This is similar to the
value of @code{current-time}; see @ref{Time of Day}.)

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

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

@item

@end table
@end defun

@node Locating Files
@subsection How to Locate Files in Standard Places
@cindex locate files
@cindex find files

  This section explains how to search for a file in a list of
directories.  One example is when you need to look for a program's
executable file, e.g., to find out whether a given program is
installed on the user's system.  Another example is the search for
Lisp libraries (@pxref{Library Search}).  Such searches generally need
to try various possible file name extensions, in addition to various
possible directories.  Emacs provides a function for such a
generalized search for a file.

For compatibility, @var{predicate} can also be one of the symbols
@code{executable}, @code{readable}, @code{writable}, @code{exists}, or
a list of one or more of these symbols.
@end defun

@cindex find executable program
@defun executable-find program
This function searches for the executable file of the named
@var{program} and returns the full absolute name of the executable,
including its file-name extensions, if any.  It returns @code{nil} if
the file is not found.  The functions searches in all the directories

@code{exec-suffixes}.
@end defun

@node Changing Files
@section Changing File Names and Attributes
@cindex renaming files
@cindex copying files
@cindex deleting files
@cindex linking files
@cindex setting modes of files

which generate the listing with Lisp code.
@end defvar

@node Create/Delete Dirs
@section Creating and Deleting Directories
@c Emacs 19 features

  Most Emacs Lisp file-manipulation functions get errors when used on
files that are directories.  For example, you cannot delete a directory
with @code{delete-file}.  These special functions exist to create and

90796:4ef881a120fe

in the list @code{find-file-hook}.
@end defun

@node Saving Buffers
@section Saving Buffers
@cindex saving buffers

  When you edit a file in Emacs, you are actually working on a buffer
that is visiting that file---that is, the contents of the file are
copied into the buffer and the copy is what you edit.  Changes to the
buffer do not change the file until you @dfn{save} the buffer, which

Name}).

@node Reading from Files
@comment  node-name,  next,  previous,  up
@section Reading from Files
@cindex reading from files

  You can copy a file from the disk and insert it into a buffer
using the @code{insert-file-contents} function.  Don't use the user-level
command @code{insert-file} in a Lisp program, as that sets the mark.

@ref{Magic File Names}.

@node Writing to Files
@comment  node-name,  next,  previous,  up
@section Writing to Files
@cindex writing to files

  You can write the contents of a buffer, or part of a buffer, directly
to a file on disk using the @code{append-to-file} and
@code{write-region} functions.  Don't use these functions to write to
files that are being visited; that could cause confusion in the

@end defmac

@node File Locks
@section File Locks
@cindex file locks
@cindex lock file

  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.  (File locks are not implemented on Microsoft systems.)

for its usual definition is in @file{userlock.el}.
@end defun

@node Information about Files
@section Information about Files
@cindex file, information about

  The functions described in this section all operate on strings that
designate file names.  With a few exceptions, all the functions have
names that begin with the word @samp{file}.  These functions all
return information about actual files or directories, so their

the second has the low 16 bits.  (This is similar to the
value of @code{current-time}; see @ref{Time of Day}.)

@item
The time of last modification as a list of two integers (as above).
@cindex modification time of file

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

@item

@end table
@end defun

@node Locating Files
@subsection How to Locate Files in Standard Places
@cindex locate file in path
@cindex find file in path

  This section explains how to search for a file in a list of
directories (a @dfn{path}).  One example is when you need to look for
a program's executable file, e.g., to find out whether a given program
is installed on the user's system.  Another example is the search for
Lisp libraries (@pxref{Library Search}).  Such searches generally need
to try various possible file name extensions, in addition to various
possible directories.  Emacs provides a function for such a
generalized search for a file.

For compatibility, @var{predicate} can also be one of the symbols
@code{executable}, @code{readable}, @code{writable}, @code{exists}, or
a list of one or more of these symbols.
@end defun

@defun executable-find program
This function searches for the executable file of the named
@var{program} and returns the full absolute name of the executable,
including its file-name extensions, if any.  It returns @code{nil} if
the file is not found.  The functions searches in all the directories

@code{exec-suffixes}.
@end defun

@node Changing Files
@section Changing File Names and Attributes
@c @cindex renaming files  Duplicates rename-file
@cindex copying files
@cindex deleting files
@cindex linking files
@cindex setting modes of files

which generate the listing with Lisp code.
@end defvar

@node Create/Delete Dirs
@section Creating and Deleting Directories
@cindex creating and deleting directories
@c Emacs 19 features

  Most Emacs Lisp file-manipulation functions get errors when used on
files that are directories.  For example, you cannot delete a directory
with @code{delete-file}.  These special functions exist to create and