@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/files
@node Files, Backups and Auto-Saving, Documentation, Top
@comment  node-name,  next,  previous,  up
@c @chapter Files
@chapter $B%U%!%$%k(B

@c   In Emacs, you can find, create, view, save, and otherwise work with
@c files and file directories.  This chapter describes most of the
@c file-related functions of Emacs Lisp, but a few others are described in
@c @ref{Buffers}, and those related to backups and auto-saving are
@c described in @ref{Backups and Auto-Saving}.
Emacs$B$G$O!"%U%!%$%k$d%G%#%l%/%H%j$r(B
$BC5$7$?$j!":n@.$7$?$j!"D/$a$?$j!"J]B8$7$?$j!"$=$NB>$N$3$H$r$G$-$^$9!#(B
$BK\>O$G$O!"(BEmacs Lisp$B$N%U%!%$%k4XO"$N4X?t$N$[$H$s$I$K$D$$$F@bL@$7$^$9$,!"(B
$BB>$N0lIt$O(B@ref{Buffers}$B$G!"%P%C%/%"%C%W$d<+F0J]B8$K4X$9$k$3$H$O(B
@ref{Backups and Auto-Saving}$B$G@bL@$7$^$9!#(B

@c   Many of the file functions take one or more arguments that are file
@c names.  A file name is actually a string.  Most of these functions
@c expand file name arguments by calling @code{expand-file-name}, so that
@c @file{~} is handled correctly, as are relative file names (including
@c @samp{../}).  These functions don't recognize environment variable
@c substitutions such as @samp{$HOME}.  @xref{File Name Expansion}.
$B%U%!%$%k4X?t$NB?$/$O!"%U%!%$%kL>$N0z?t$r(B1$B$D$J$$$7J#?t8D<h$j$^$9!#(B
$B%U%!%$%kL>$O<B:]$K$OJ8;zNs$G$9!#(B
$B$3$l$i$N$[$H$s$I$N4X?t$G$O!"(B@code{expand-file-name}$B$r8F$S=P$7$F(B
$B%U%!%$%kL>0z?t$rE83+$9$k$3$H$G(B@file{~}$B$d(B
$B!J(B@samp{../}$B$r4^$`!KAjBP%U%!%$%kL>$r@5$7$/=hM}$7$^$9!#(B
$B$3$l$i$N4X?t$O!"(B@samp{$HOME}$B$J$I$N4D6-JQ?tCV49$OG'<1$7$^$;$s!#(B
@xref{File Name Expansion}$B!#(B

@menu
* Visiting Files::           Reading files into Emacs buffers for editing.
* Saving Buffers::           Writing changed buffers back into files.
* Reading from Files::       Reading files into buffers without visiting.
* Writing to Files::         Writing new files from parts of buffers.
* File Locks::               Locking and unlocking files, to prevent
                               simultaneous editing by two people.
* Information about Files::  Testing existence, accessibility, size of files.
* Changing Files::           Renaming files, changing protection, etc.
* 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.
* Magic File Names::	     Defining "magic" special handling
			       for certain file names.
* Format Conversion::        Conversion to and from various file formats.
@end menu

@node Visiting Files
@c @section Visiting Files
@section $B%U%!%$%k$NK,Ld(B
@c @cindex finding files
@c @cindex visiting files
@cindex $B%U%!%$%k$rC5$9(B
@cindex $B%U%!%$%k$rK,Ld$9$k(B

@c   Visiting a file means reading a file into a buffer.  Once this is
@c done, we say that the buffer is @dfn{visiting} that file, and call the
@c file ``the visited file'' of the buffer.
$B%U%!%$%k$rK,Ld$9$k$H$O!"%U%!%$%k$r%P%C%U%!$KFI$_9~$`$3$H$G$9!#(B
$B$$$C$?$s$3$&$9$k$H!"%P%C%U%!$O$=$N%U%!%$%k$r(B
@dfn{$BK,Ld$7$F$$$k(B}$B!J(Bvisiting$B!K$H$$$$!"(B
$B$=$N%U%!%$%k$r%P%C%U%!$N!XK,Ld$7$F$$$k%U%!%$%k!Y$H8F$S$^$9!#(B

@c   A file and a buffer are two different things.  A file is information
@c recorded permanently in the computer (unless you delete it).  A buffer,
@c on the other hand, is information inside of Emacs that will vanish at
@c the end of the editing session (or when you kill the buffer).  Usually,
@c a buffer contains information that you have copied from a file; then we
@c say the buffer is visiting that file.  The copy in the buffer is what
@c you modify with editing commands.  Such changes to the buffer do not
@c change the file; therefore, to make the changes permanent, you must
@c @dfn{save} the buffer, which means copying the altered buffer contents
@c back into the file.
$B%U%!%$%k$H%P%C%U%!$O(B2$B$D$N0[$J$k$b$N$G$9!#(B
$B%U%!%$%k$O!"%3%s%T%e!<%?Fb$K!JFI<T$,:o=|$7$J$$8B$j!K915WE*$K(B
$B5-O?$5$l$F$$$k>pJs$G$9!#(B
$B0lJ}!"%P%C%U%!$O(BEmacs$BFbIt$K$"$k>pJs$G$"$j!"(B
$BJT=8%;%C%7%g%s$r=*N;$9$k!J$"$k$$$O%P%C%U%!$r:o=|$9$k!K$H>C$($F$7$^$$$^$9!#(B
$BDL>o!"%P%C%U%!$K$O%U%!%$%k$+$i%3%T!<$7$?>pJs$,$"$j$^$9!#(B
$B$D$^$j!"%P%C%U%!$O$=$N%U%!%$%k$rK,Ld$7$F$$$k$N$G$9!#(B
$BFI<T$O!"%P%C%U%!Fb$N%3%T!<$rJT=8%3%^%s%I$G=$@5$9$k$N$G$9!#(B
$B%P%C%U%!$KBP$9$k$=$N$h$&$JJQ99$G$O!"%U%!%$%k$OJQ99$7$^$;$s!#(B
$B$7$?$,$C$F!"JQ99$r915WE*$J$b$N$K$9$k$K$O!"(B
$BFI<T$O%P%C%U%!$r(B@dfn{$BJ]B8(B}$B!J(Bsave$B!K$9$k!"$D$^$j!"(B
$B%P%C%U%!$NJQ99$7$?FbMF$r%U%!%$%k$K%3%T!<$7La$9I,MW$,$"$j$^$9!#(B

@c   In spite of the distinction between files and buffers, people often
@c refer to a file when they mean a buffer and vice-versa.  Indeed, we say,
@c ``I am editing a file,'' rather than, ``I am editing a buffer that I
@c will soon save as a file of the same name.''  Humans do not usually need
@c to make the distinction explicit.  When dealing with a computer program,
@c however, it is good to keep the distinction in mind.
$B%U%!%$%k$H%P%C%U%!$N6hJL$K$b4X$o$i$:!"(B
$B%P%C%U%!$r0UL#$7$F%U%!%$%k$H$$$C$?$j!"$=$N5U$N$$$$J}$r$7$P$7$P$7$^$9!#(B
$B$b$A$m$s!"!XF1$8L>A0$N%U%!%$%k$K$?$@$A$KJ]B8$9$k$D$b$j$G%P%C%U%!$r(B
$BJT=8$7$F$$$k!Y$H$O$$$o$:$K!X%U%!%$%k$rJT=8$7$F$$$k!Y$H$$$$$^$9!#(B
$B$7$P$7$P!"?M4V$OL@3N$K6hJL$9$kI,MW$O$"$j$^$;$s!#(B
$B$7$+$7!"%3%s%T%e!<%?%W%m%0%i%`$r07$&$&$($G$O!"(B
$B6hJL$r?4F@$F$*$/$3$H$,$h$$$N$G$9!#(B

@menu
* Visiting Functions::         The usual interface functions for visiting.
* Subroutines of Visiting::    Lower-level subroutines that they use.
@end menu

@node Visiting Functions
@c @subsection Functions for Visiting Files
@subsection $B%U%!%$%k$rK,Ld$9$k4X?t(B

@c   This section describes the functions normally used to visit files.
@c For historical reasons, these functions have names starting with
@c @samp{find-} rather than @samp{visit-}.  @xref{Buffer File Name}, for
@c functions and variables that access the visited file name of a buffer or
@c that find an existing buffer by its visited file name.
$BK\@a$G$O!"%U%!%$%k$rK,Ld$9$k$?$a$KDL>o;H$&4X?t$K$D$$$F=R$Y$^$9!#(B
$BNr;KE*$JM}M3$G!"$3$l$i$N4X?t$O(B@samp{visit-}$B$G$J$/(B@samp{find-}$B$H$$$&(B
$BL>A0$G;O$^$j$^$9!#(B
$B%P%C%U%!$GK,Ld$7$?%U%!%$%k$NL>A0$r;2>H$9$k$?$a$N4X?t$dJQ?t!"$J$i$S$K!"(B
$BK,Ld$7$?%U%!%$%k$NL>A0$G4{B8%P%C%U%!$rC5$9$?$a$N4X?t$dJQ?t$K$D$$$F$O!"(B
@xref{Buffer File Name}$B!#(B

@c   In a Lisp program, if you want to look at the contents of a file but
@c not alter it, the fastest way is to use @code{insert-file-contents} in a
@c temporary buffer.  Visiting the file is not necessary and takes longer.
@c @xref{Reading from Files}.
Lisp$B%W%m%0%i%`$K$*$$$F!"%U%!%$%k$NFbMF$rJQ99$;$:$K$=$NFbMF$rD4$Y$?$$$H$-$K$O!"(B
$B$b$C$H$bB.$$J}K!$O0l;~E*$J%P%C%U%!$G(B@code{insert-file-contents}$B$r(B
$B;H$&$3$H$G$9!#(B
$B%U%!%$%k$rK,Ld$9$kI,MW$O$"$j$^$;$s$7!"$=$l$K$OM>7W$K;~4V$,$+$+$j$^$9!#(B
@xref{Reading from Files}$B!#(B

@c @deffn Command find-file filename
@deffn $B%3%^%s%I(B find-file filename
@c This command selects a buffer visiting the file @var{filename},
@c using an existing buffer if there is one, and otherwise creating a 
@c new buffer and reading the file into it.  It also returns that buffer.
$B$3$N%3%^%s%I$O%U%!%$%k(B@var{filename}$B$rK,Ld$7$?%P%C%U%!$rA*Br$9$k!#(B
$B$=$N$h$&$J%P%C%U%!$,4{B8$J$i$PEv3:%P%C%U%!$r;H$&!#(B
$B$5$b$J$1$l$P!"?7$?$J%P%C%U%!$r:n@.$7$F%U%!%$%k$rFI$_9~$`!#(B
$BEv3:%P%C%U%!$rJV$9!#(B

@c The body of the @code{find-file} function is very simple and looks
@c like this:
$B4X?t(B@code{find-file}$B$NK\BN$OHs>o$K4JC1$G!"$D$.$N$H$*$j$G$"$k!#(B

@example
(switch-to-buffer (find-file-noselect filename))
@end example

@noindent
@c (See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
$B!J(B@ref{Displaying Buffers}$B$N(B@code{switch-to-buffer}$B$r;2>H!#!K(B

@c When @code{find-file} is called interactively, it prompts for
@c @var{filename} in the minibuffer.
@code{find-file}$B$,BPOCE*$K8F$S=P$5$l$k$H!"(B
$B%_%K%P%C%U%!$G(B@var{filename}$B$rLd$$9g$o$;$k!#(B
@end deffn

@defun find-file-noselect filename &optional nowarn rawfile
@c This function is the guts of all the file-visiting functions.  It finds
@c or creates a buffer visiting the file @var{filename}, and returns it.
@c It uses an existing buffer if there is one, and otherwise creates a new
@c buffer and reads the file into it.  You may make the buffer current or
@c display it in a window if you wish, but this function does not do so.
$B$3$N4X?t$O!"%U%!%$%k$rK,Ld$9$k$9$Y$F$N4X?t$N4p$G$"$k!#(B
$B%U%!%$%k(B@var{filename}$B$rK,Ld$7$?!?$9$k%P%C%U%!$rC5$7!?:n@.$7!"(B
$BEv3:%P%C%U%!$rJV$9!#(B
$B$=$N$h$&$J%P%C%U%!$,4{B8$J$i$PEv3:%P%C%U%!$r;H$&!#(B
$B$5$b$J$1$l$P!"?7$?$J%P%C%U%!$r:n@.$7$F%U%!%$%k$rFI$_9~$`!#(B
$BI,MW$K1~$8$F!"%P%C%U%!$r%+%l%s%H%P%C%U%!$K$7$?$j(B
$B%&%#%s%I%&$KI=<($G$-$k$,!"$3$N4X?t$O$=$3$^$G$O9T$o$J$$!#(B

@c When @code{find-file-noselect} uses an existing buffer, it first
@c verifies that the file has not changed since it was last visited or
@c saved in that buffer.  If the file has changed, then this function asks
@c the user whether to reread the changed file.  If the user says
@c @samp{yes}, any changes previously made in the buffer are lost.
@code{find-file-noselect}$B$,4{B8%P%C%U%!$r;H$&$H$-$K$O!"(B
$B%U%!%$%k$NFbMF$,Ev3:%P%C%U%!$K:G8e$KK,Ld$7$F$+$i!"$"$k$$$O!"(B
$BEv3:%P%C%U%!$r:G8e$KJ]B8$7$F$+$iJQ99$5$l$?$+$I$&$+$^$:3NG'$9$k!#(B
$B%U%!%$%k$,JQ99$5$l$F$$$l$P!"$3$N4X?t$OJQ99$5$l$?%U%!%$%k$r(B
$B:FEYFI$_9~$`$+$I$&$+%f!<%6!<$KLd$$9g$o$;$k!#(B
$B%f!<%6!<$,(B@samp{yes}$B$HEz$($k$H!"%P%C%U%!Fb$NJQ99$OGK4~$5$l$k!#(B

@c This function displays warning or advisory messages in various peculiar
@c cases, unless the optional argument @var{nowarn} is non-@code{nil}.  For
@c example, if it needs to create a buffer, and there is no file named
@c @var{filename}, it displays the message @samp{New file} in the echo
@c area, and leaves the buffer empty.
$B>JN,2DG=$J0z?t(B@var{nowarn}$B$,(B@code{nil}$B$G$"$k$H!"(B
$B$3$N4X?t$O$5$^$6$^$J>lLL$G7Y9p!?=u8@%a%C%;!<%8$rI=<($9$k!#(B
$B$?$H$($P!"%P%C%U%!$r:n@.$9$kI,MW$,$"$j!"$+$D!"(B
$B;XDj$7$?%U%!%$%k(B@var{filename}$B$,$J$$>l9g$K$O!"(B
$B%(%3!<NN0h$K%a%C%;!<%8(B@samp{New file}$B$rI=<($7!"%P%C%U%!$O6u$K$7$F$*$/!#(B

@c The @code{find-file-noselect} function normally calls
@c @code{after-find-file} after reading the file (@pxref{Subroutines of
@c Visiting}).  That function sets the buffer major mode, parses local
@c variables, warns the user if there exists an auto-save file more recent
@c than the file just visited, and finishes by running the functions in
@c @code{find-file-hooks}.
$B4X?t(B@code{find-file-noselect}$B$O!"(B
$B%U%!%$%k$rFI$_9~$_=*$($k$HDL>o(B@code{after-find-file}$B$r8F$S=P$9(B
$B!J(B@pxref{Subroutines of Visiting}$B!K!#(B
$B$=$N4X?t$O!"%P%C%U%!$N%a%8%c!<%b!<%I$r@_Dj$7!"%m!<%+%kJQ?t$r2r@O$7!"(B
$BK,Ld$7$?%U%!%$%k$h$j?7$7$$<+F0J]B8%U%!%$%k$,B8:_$9$k$H%f!<%6!<$K7Y9p$rH/$7!"(B
@code{find-file-hooks}$B$N4X?t$r<B9T$7$F=hM}$r=*$($k!#(B

@c If the optional argument @var{rawfile} is non-@code{nil}, then
@c @code{after-find-file} is not called, and the
@c @code{find-file-not-found-hooks} are not run in case of failure.  What's
@c more, a non-@code{nil} @var{rawfile} value suppresses coding system
@c conversion (@pxref{Coding Systems}) and format conversion (@pxref{Format
@c Conversion}).
$B>JN,2DG=$J0z?t(B@var{rawfile}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
@code{after-find-file}$B$r8F$S=P$5$:!"(B
$B<:GT$7$F$b(B@code{find-file-not-found-hooks}$B$r<B9T$7$J$$!#(B
$B$5$i$K!"(B@var{rawfile}$B$NCM$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B%3!<%G%#%s%0%7%9%F%`$NJQ49!J(B@pxref{Coding Systems}$B!K$d(B
$B=q<0JQ49!J(B@pxref{Format Conversion}$B!K$b9T$o$J$$!#(B

@c The @code{find-file-noselect} function returns the buffer that is
@c visiting the file @var{filename}.
$B4X?t(B@code{find-file-noselect}$B$O!"(B
$B%U%!%$%k(B@var{filename}$B$rK,Ld$7$?%P%C%U%!$rJV$9!#(B

@example
@group
(find-file-noselect "/etc/fstab")
     @result{} #<buffer fstab>
@end group
@end example
@end defun

@c @deffn Command find-file-other-window filename
@deffn $B%3%^%s%I(B find-file-other-window filename
@c This command selects a buffer visiting the file @var{filename}, but
@c does so in a window other than the selected window.  It may use another
@c existing window or split a window; see @ref{Displaying Buffers}.
$B$3$N%3%^%s%I$O!"A*Br$7$F$$$k%&%#%s%I%&0J30$N%&%#%s%I%&$K$*$$$F!"(B
$B%U%!%$%k(B@var{filename}$B$rK,Ld$7$?%P%C%U%!$rA*Br$9$k!#(B
$BJL$N4{B8%&%#%s%I%&$r;H$&$+!"%&%#%s%I%&$rJ,3d$9$k!#(B
@ref{Displaying Buffers}$B$r;2>H!#(B

@c When this command is called interactively, it prompts for
@c @var{filename}.
$B$3$N%3%^%s%I$,BPOCE*$K8F$S=P$5$l$k$H!"(B
@var{filename}$B$rLd$$9g$o$;$k!#(B
@end deffn

@c @deffn Command find-file-read-only filename
@deffn $B%3%^%s%I(B find-file-read-only filename
@c This command selects a buffer visiting the file @var{filename}, like
@c @code{find-file}, but it marks the buffer as read-only.  @xref{Read Only
@c Buffers}, for related functions and variables.
$B$3$N%3%^%s%I$O!"(B@code{find-file}$B$N$h$&$K%U%!%$%k(B@var{filename}$B$rK,Ld$7$?(B
$B%P%C%U%!$rA*Br$9$k$,!"Ev3:%P%C%U%!$OFI$_=P$7@lMQ$H$J$k!#(B
@xref{Read Only Buffers}$B!#(B

@c When this command is called interactively, it prompts for
@c @var{filename}.
$B$3$N%3%^%s%I$,BPOCE*$K8F$S=P$5$l$k$H!"(B
@var{filename}$B$rLd$$9g$o$;$k!#(B
@end deffn

@c @deffn Command view-file filename
@deffn $B%3%^%s%I(B view-file filename
@c This command visits @var{filename} using View mode, returning to the
@c previous buffer when you exit View mode.  View mode is a minor mode that
@c provides commands to skim rapidly through the file, but does not let you
@c modify the text.  Entering View mode runs the normal hook
@c @code{view-mode-hook}.  @xref{Hooks}.
$B$3$N%3%^%s%I$O!"1\Mw!J(Bview$B!K%b!<%I$G(B@var{filename}$B$rK,Ld$7!"(B
$B1\Mw!J(Bview$B!K%b!<%I$rH4$1$k$H$=$l0JA0$N%P%C%U%!$KLa$k!#(B
$B1\Mw!J(Bview$B!K%b!<%I$O!"%U%!%$%k$rAGAa$/D/$a$k$?$a$N%3%^%s%I$rM?$($k$,(B
$B%F%-%9%H$NJQ99$O5v$5$J$$%^%$%J%b!<%I$G$"$k!#(B
$B1\Mw!J(Bview$B!K%b!<%I$KF~$k$H!"%N!<%^%k%U%C%/(B@code{view-mode-hook}$B$r<B9T$9$k!#(B
@pxref{Hooks}$B!#(B

@c When @code{view-file} is called interactively, it prompts for
@c @var{filename}.
@code{view-file}$B$,BPOCE*$K8F$S=P$5$l$k$H!"(B
@var{filename}$B$rLd$$9g$o$;$k!#(B
@end deffn

@defvar find-file-hooks
@c The value of this variable is a list of functions to be called after a
@c file is visited.  The file's local-variables specification (if any) will
@c have been processed before the hooks are run.  The buffer visiting the
@c file is current when the hook functions are run.
$B$3$NJQ?t$NCM$O!"%U%!%$%k$rK,Ld8e$K8F$S=P$5$l$k4X?t$N%j%9%H$G$"$k!#(B
$B%U%!%$%k$K%m!<%+%kJQ?t;XDj!J$,$"$l$P!K$O!"(B
$B%U%C%/$r<B9T$9$k$^$($K=hM}$5$l$k!#(B
$B%U%C%/4X?t$,<B9T$5$l$H$-$K$O!"(B
$B%U%!%$%k$rK,Ld$7$?%P%C%U%!$O%+%l%s%H%P%C%U%!$K$J$C$F$$$k!#(B

@c This variable works just like a normal hook, but we think that renaming
@c it would not be advisable.  @xref{Hooks}.
$B$3$NJQ?t$O%N!<%^%k%U%C%/$N$h$&$KF0:n$9$k$,!"(B
$B2~L>$9$Y$-$G$O$J$$$H9M$($F$$$k!#(B
@pxref{Hooks}$B!#(B
@end defvar

@defvar find-file-not-found-hooks
@c The value of this variable is a list of functions to be called when
@c @code{find-file} or @code{find-file-noselect} is passed a nonexistent
@c file name.  @code{find-file-noselect} calls these functions as soon as
@c it detects a nonexistent file.  It calls them in the order of the list,
@c until one of them returns non-@code{nil}.  @code{buffer-file-name} is
@c already set up.
$B$3$NJQ?t$NCM$O!"(B@code{find-file}$B$d(B@code{find-file-noselect}$B$K(B
$BB8:_$7$J$$%U%!%$%k$rM?$($?$H$-$K8F$S=P$5$l$k4X?t$N%j%9%H$G$"$k!#(B
@code{find-file-noselect}$B$O!"%U%!%$%k$,B8:_$7$J$$$3$H$,$o$+$k$H(B
$B$?$@$A$K$3$l$i$N4X?t$r8F$S=P$9!#(B
@code{nil}$B0J30$NCM$,JV$5$l$k$^$G!"%j%9%H$K8=$l$k=g$K8F$S=P$9!#(B
@code{buffer-file-name}$B$O@_Dj:Q$_$G$"$k!#(B

@c This is not a normal hook because the values of the functions are
@c used, and in many cases only some of the functions are called.
$B4X?t$NCM$r;H$$!"$7$+$b!"0lIt$N4X?t$@$1$r8F$S=P$9$N$G!"(B
$B$3$l$O%N!<%^%k%U%C%/$G$O$J$$!#(B
@end defvar

@node Subroutines of Visiting
@comment  node-name,  next,  previous,  up
@c @subsection Subroutines of Visiting
@subsection $BK,Ld$9$k$?$a$N%5%V%k!<%F%#%s(B

@c   The @code{find-file-noselect} function uses two important subroutines
@c which are sometimes useful in user Lisp code: @code{create-file-buffer}
@c and @code{after-find-file}.  This section explains how to use them.
$B4X?t(B@code{find-file-noselect}$B$O!"%f!<%6!<$N(BLisp$B%3!<%I$G$bM-MQ$J(B
2$B$D$N=EMW$J%5%V%k!<%F%#%s!"(B@code{create-file-buffer}$B$H(B
@code{after-find-file}$B$r;H$$$^$9!#(B
$BK\@a$G$O$=$l$i$N;H$$J}$r@bL@$7$^$9!#(B

@defun create-file-buffer filename
@c This function creates a suitably named buffer for visiting
@c @var{filename}, and returns it.  It uses @var{filename} (sans directory)
@c as the name if that name is free; otherwise, it appends a string such as
@c @samp{<2>} to get an unused name.  See also @ref{Creating Buffers}.
$B$3$N4X?t$O!"(B@var{filename}$B$rK,Ld$9$k$N$KE,$9$k$h$&$KL?L>$7$?(B
$B%P%C%U%!$r:n@.$7$=$l$rJV$9!#(B
$B!J%G%#%l%/%H%j$r=|30$7$?!K(B@var{filename}$B$,;HMQCf$NL>A0$G$J$1$l$P!"(B
$B$=$l$rL>A0$H$9$k!#(B
$B$5$b$J$1$l$P!"L$;HMQ$NL>A0$rF@$k$?$a$K(B@samp{<2>}$B$J$I$NJ8;zNs$rIU2C$9$k!#(B
@ref{Creating Buffers}$B$b;2>H!#(B

@c @strong{Please note:} @code{create-file-buffer} does @emph{not}
@c associate the new buffer with a file and does not select the buffer.
@c It also does not use the default major mode.
@strong{$BCm0U!'(B}@code{ }
@code{create-file-buffer}$B$O!"(B
$B?7$?$J%P%C%U%!$r%U%!%$%k$KBP1~IU$1(B@emph{$B$J$$(B}$B$7!"(B
$BEv3:%P%C%U%!$rA*Br$7$J$$!#(B
$B%G%U%)%k%H$N%a%8%c!<%b!<%I$b;H$o$J$$!#(B

@example
@group
(create-file-buffer "foo")
     @result{} #<buffer foo>
@end group
@group
(create-file-buffer "foo")
     @result{} #<buffer foo<2>>
@end group
@group
(create-file-buffer "foo")
     @result{} #<buffer foo<3>>
@end group
@end example

@c This function is used by @code{find-file-noselect}.
@c It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
$B$3$N4X?t$O(B@code{find-file-noselect}$B$G;H$o$l$k!#(B
$B$3$N4X?t$O(B@code{generate-new-buffer}$B!J(B@pxref{Creating Buffers}$B!K$r;H$&!#(B
@end defun

@defun after-find-file &optional error warn
@c This function sets the buffer major mode, and parses local variables
@c (@pxref{Auto Major Mode}).  It is called by @code{find-file-noselect}
@c and by the default revert function (@pxref{Reverting}).
$B$3$N4X?t$O!"%P%C%U%!$N%a%8%c!<%b!<%I$r@_Dj$7!"(B
$B%m!<%+%kJQ?t$r2r@O$9$k!J(B@pxref{Auto Major Mode}$B!K!#(B
@code{find-file-noselect}$B$d(B
$B%G%U%)%k%H$NI|85=hM}4X?t!J(B@pxref{Reverting}$B!K$+$i8F$P$l$k!#(B

@c @cindex new file message
@c @cindex file open error
@cindex $B?75,%U%!%$%k%a%C%;!<%8(B
@cindex $B%U%!%$%k%*!<%W%s%(%i!<(B
@c If reading the file got an error because the file does not exist, but
@c its directory does exist, the caller should pass a non-@code{nil} value
@c for @var{error}.  In that case, @code{after-find-file} issues a warning:
@c @samp{(New File)}.  For more serious errors, the caller should usually not
@c call @code{after-find-file}.
$B%G%#%l%/%H%j$O$"$k$N$K%U%!%$%k$,B8:_$7$J$$$?$a$K(B
$B%U%!%$%k$NFI$_9~$_$,%(%i!<$K$J$C$?>l9g$K$O!"(B
$B8F$S=P$7B&$O(B@var{error}$B$NCM$H$7$F(B@code{nil}$B0J30$rEO$9$3$H!#(B
$B$=$N>l9g!"(B@code{after-find-file}$B$O7Y9p(B@samp{(New File)}$B$rI=<($9$k!#(B
$B$h$j=EBg$J%(%i!<$N>l9g$K$O!"(B@code{after-find-file}$B$r8F$S=P$9$Y$-$G$J$$!#(B

@c If @var{warn} is non-@code{nil}, then this function issues a warning
@c if an auto-save file exists and is more recent than the visited file.
@var{warn}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B<+F0J]B8%U%!%$%k$,B8:_$7$=$l$,K,Ld$7$?%U%!%$%k$h$j?7$7$$>l9g$K$O!"(B
$B$3$N4X?t$O7Y9p$rH/$9$k!#(B

@c The last thing @code{after-find-file} does is call all the functions
@c in the list @code{find-file-hooks}.
@code{after-find-file}$B$,:G8e$K9T$&$3$H$O!"(B
$B%j%9%H(B@code{find-file-hooks}$BFb$N$9$Y$F$N4X?t$r8F$S=P$9$3$H$G$"$k!#(B
@end defun

@node Saving Buffers
@c @section Saving Buffers
@section $B%P%C%U%!$NJ]B8(B

@c   When you edit a file in Emacs, you are actually working on a buffer
@c that is visiting that file---that is, the contents of the file are
@c copied into the buffer and the copy is what you edit.  Changes to the
@c buffer do not change the file until you @dfn{save} the buffer, which
@c means copying the contents of the buffer into the file.
Emacs$B$G%U%!%$%k$rJT=8$9$k$H$-$K$O!"(B
$B%U%!%$%k$rK,Ld$7$?%P%C%U%!$r<B:]$K$O07$C$F$$$^$9!#(B
$B$D$^$j!"%U%!%$%k$NFbMF$O%P%C%U%!$K%3%T!<$5$l!"(B
$B$=$N%3%T!<$rJT=8$7$F$$$k$N$G$9!#(B
$B%P%C%U%!$rJQ99$7$F$b!"Ev3:%P%C%U%!$r(B@dfn{$BJ]B8(B}$B!J(Bsave$B!K$9$k$^$G!"(B
$B$D$^$j!"%P%C%U%!$NFbMF$r%U%!%$%k$X%3%T!<$9$k$^$G$O!"(B
$B%U%!%$%k$rJQ99$7$^$;$s!#(B

@c @deffn Command save-buffer &optional backup-option
@deffn $B%3%^%s%I(B save-buffer &optional backup-option
@c This function saves the contents of the current buffer in its visited
@c file if the buffer has been modified since it was last visited or saved.
@c Otherwise it does nothing.
$B$3$N4X?t$O!":G8e$KK,Ld!?J]B8$7$F$+$i%+%l%s%H%P%C%U%!$,JQ99$5$l$F$$$l$P!"(B
$B%+%l%s%H%P%C%U%!$NFbMF$rK,Ld$7$F$$$k%U%!%$%k$XJ]B8$9$k!#(B

@c @code{save-buffer} is responsible for making backup files.  Normally,
@c @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
@c file only if this is the first save since visiting the file.  Other
@c values for @var{backup-option} request the making of backup files in
@c other circumstances:
@code{save-buffer}$B$O!"%P%C%/%"%C%W$N:n@.$K@UG$$,$"$k!#(B
$BDL>o!"(B@var{backup-option}$B$O(B@code{nil}$B$G$"$j!"(B
@code{save-buffer}$B$O!"%U%!%$%k$rK,Ld$7$F$+$i(B
$B:G=i$KJ]B8$9$k$H$-$K$N$_%P%C%/%"%C%W%U%!%$%k$r:n@.$9$k!#(B
@var{backup-option}$B$,JL$NCM$G$"$k$H!"(B
$BJL$N>lLL$G$b%P%C%/%"%C%W%U%!%$%k$r:n@.$9$k$3$H$r;X<($9$k!#(B

@itemize @bullet
@item
@c With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
@c @code{save-buffer} function marks this version of the file to be
@c backed up when the buffer is next saved.
$B0z?t$,(B1$B$D$+(B3$B$D$N(B@kbd{C-u}$B$rH?1G$7$?(B4$B$+(B64$B$G$"$k$H!"(B
$B4X?t(B@code{save-buffer}$B$O!"%P%C%U%!$r$D$.$KJ]B8$7$?$H$-$K(B
$B%U%!%$%k$N8=:_$NHG$r%P%C%/%"%C%W$9$k$h$&$K0u$rIU$1$k!#(B

@item
@c With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
@c @code{save-buffer} function unconditionally backs up the previous
@c version of the file before saving it.
$B0z?t$,(B2$B$D$+(B3$B$D$N(B@kbd{C-u}$B$rH?1G$7$?(B16$B$+(B64$B$G$"$k$H!"(B
@code{save-buffer}$B$O!"J]B8$9$k$^$($KL5>r7o$K(B
$B%U%!%$%k$N$^$($NHG$r%P%C%/%"%C%W$9$k!#(B
@end itemize
@end deffn

@c @deffn Command save-some-buffers &optional save-silently-p exiting
@deffn $B%3%^%s%I(B save-some-buffers &optional save-silently-p exiting
@c This command saves some modified file-visiting buffers.  Normally it
@c asks the user about each buffer.  But if @var{save-silently-p} is
@c non-@code{nil}, it saves all the file-visiting buffers without querying
@c the user.
$B$3$N%3%^%s%I$O!"%U%!%$%k$rK,Ld$7$F$$$kJQ99$5$l$?%P%C%U%!$rJ]B8$9$k!#(B
$BDL>o!"3F%P%C%U%!$K$D$$$F%f!<%6!<$KLd$$9g$o$;$k!#(B
$B$7$+$7!"(B@var{save-silently-p}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B%f!<%6!<$KLd$$9g$o$;$:$K%U%!%$%k$rK,Ld$7$F$$$k%P%C%U%!$r$9$Y$FJ]B8$9$k!#(B

@c The optional @var{exiting} argument, if non-@code{nil}, requests this
@c function to offer also to save certain other buffers that are not
@c visiting files.  These are buffers that have a non-@code{nil}
@c buffer-local value of @code{buffer-offer-save}.  (A user who says yes to
@c saving one of these is asked to specify a file name to use.)  The
@c @code{save-buffers-kill-emacs} function passes a non-@code{nil} value
@c for this argument.
$B>JN,2DG=$J0z?t(B@var{exiting}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B$3$N4X?t$O!"%U%!%$%k$rK,Ld$7$F$$$J$$$"$k<o$N%P%C%U%!$rJ]B8$9$k5!2q$bM?$($k!#(B
@code{buffer-offer-save}$B$N%P%C%U%!%m!<%+%k$JCM$,(B
@code{nil}$B0J30$N%P%C%U%!$,BP>]$H$J$k!#(B
$B!J%f!<%6!<$,$3$l$i$N%P%C%U%!$N(B1$B$D$rJ]B8$9$k$h$&$KEz$($k$H!"(B
$B%U%!%$%kL>$r;XDj$9$k$h$&$KJ9$$$F$/$k!#!K(B
$B4X?t(B@code{save-buffers-kill-emacs}$B$O!"(B
$B$3$N0z?t$K(B@code{nil}$B0J30$NCM$rEO$9!#(B
@end deffn

@c @deffn Command write-file filename
@deffn $B%3%^%s%I(B write-file filename
@c This function writes the current buffer into file @var{filename}, makes
@c the buffer visit that file, and marks it not modified.  Then it renames
@c the buffer based on @var{filename}, appending a string like @samp{<2>}
@c if necessary to make a unique buffer name.  It does most of this work by
@c calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
@c @code{save-buffer}.
$B$3$N4X?t$O!"%+%l%s%H%P%C%U%!$r%U%!%$%k(B@var{filename}$B$KJ]B8$7!"(B
$BEv3:%U%!%$%k$rK,Ld$7$F$$$k%P%C%U%!$H$7!"$5$i$KL$JQ99$H$$$&0u$rIU$1$k!#(B
$BB3$$$F!"%P%C%U%!L>$r0l0U$K$9$k$?$a$KI,MW$J$i$P(B@samp{<2>}$B$N$h$&$J(B
$BJ8;zNs$rIU2C$7$F!"%P%C%U%!$r(B@var{filename}$B$K4p$E$$$?L>A0$K2~L>$9$k!#(B
$B$3$N=hM}$N$[$H$s$I$O!"(B@code{set-visited-file-name}$B!J(B@pxref{Buffer File Name}$B!K(B
$B$H(B@code{save-buffer}$B$r8F$S=P$7$F9T$&!#(B
@end deffn

@c   Saving a buffer runs several hooks.  It also performs format
@c conversion (@pxref{Format Conversion}), and may save text properties in
@c ``annotations'' (@pxref{Saving Properties}).
$B%P%C%U%!$rJ]B8$9$k$H!"$$$/$D$+$N%U%C%/$r<B9T$7$^$9!#(B
$B$^$?!"=q<0JQ49!J(B@pxref{Format Conversion}$B!K$r9T$$!"(B
$B%F%-%9%HB0@-$r!XCm5-!Y!J(Bannotations$B!K!J(B@pxref{Saving Properties}$B!K$K(B
$BJ]B8$9$k$3$H$b$"$j$^$9!#(B

@defvar write-file-hooks
@c The value of this variable is a list of functions to be called before
@c writing out a buffer to its visited file.  If one of them returns
@c non-@code{nil}, the file is considered already written and the rest of
@c the functions are not called, nor is the usual code for writing the file
@c executed.
$B$3$NJQ?t$NCM$O!"%P%C%U%!$rK,Ld$7$F$$$k%U%!%$%k$K=q$-=P$9$^$($K(B
$B8F$P$l$k4X?t$N%j%9%H$G$"$k!#(B
$B$=$l$i$N(B1$B$D$,(B@code{nil}$B0J30$rJV$9$H!"$9$G$K%U%!%$%k$K=q$-=P$7$?$H$_$J$7$F(B
$B;D$j$N4X?t$r8F$S=P$5$:!"%U%!%$%k$K=q$-=P$9$?$a$NDL>o$N%3!<%I$b<B9T$7$J$$!#(B

@c If a function in @code{write-file-hooks} returns non-@code{nil}, it
@c is responsible for making a backup file (if that is appropriate).
@c To do so, execute the following code:
@code{write-file-hooks}$B$N4X?t$,(B@code{nil}$B0J30$rJV$9$H$-$K$O!"(B
$B$=$N4X?t$K$O!JI,MW$J$i$P!K%P%C%/%"%C%W%U%!%$%k$r:n@.$9$k@UG$$,$"$k!#(B
$B$=$N$?$a$K$O$D$.$N%3!<%I$r<B9T$9$k!#(B

@example
(or buffer-backed-up (backup-buffer))
@end example

@c You might wish to save the file modes value returned by
@c @code{backup-buffer} and use that to set the mode bits of the file that
@c you write.  This is what @code{save-buffer} normally does.
@code{backup-buffer}$B$,JV$7$?%U%!%$%k%b!<%I$NCM$rJ]B8$7$F$*$-!"(B
$BFI<T$,=q$/%U%!%$%k$N%b!<%I$K$=$NCM$r;H$$$?$$>l9g$,$"$k!#(B
@code{save-buffer}$B$ODL>o$=$N$h$&$K$9$k!#(B

@c The hook functions in @code{write-file-hooks} are also responsible for
@c encoding the data (if desired): they must choose a suitable coding
@c system (@pxref{Lisp and Coding Systems}), perform the encoding
@c (@pxref{Explicit Encoding}), and set @code{last-coding-system-used} to
@c the coding system that was used (@pxref{Encoding and I/O}).
@code{write-file-hooks}$B$N%U%C%/4X?t$O!"(B
$B!JI,MW$J$i$P!K%G!<%?$NId9f2=$K$b@UG$$,$"$k!#(B
$BE,@Z$J%3!<%G%#%s%0%7%9%F%`!J(B@pxref{Lisp and Coding Systems}$B!K$rA*$S!"(B
$BId9f2=!J(B@pxref{Explicit Encoding}$B!K$r9T$$!"(B
$B;HMQ$7$?%3!<%G%#%s%0%7%9%F%`$r(B@code{last-coding-system-used}$B$K@_Dj$9$k(B
$B!J(B@pxref{Encoding and I/O}$B!K!#(B

@c Do not make this variable buffer-local.  To set up buffer-specific hook
@c functions, use @code{write-contents-hooks} instead.
$B$3$NJQ?t$r%P%C%U%!%m!<%+%k$K$O$7$J$$$3$H!#(B
$B%P%C%U%!8GM-$N%U%C%/4X?t$r;XDj$9$k$K$O!"(B
$B$+$o$j$K(B@code{write-contents-hooks}$B$r;H$&!#(B

@c Even though this is not a normal hook, you can use @code{add-hook} and
@c @code{remove-hook} to manipulate the list.  @xref{Hooks}.
$B$3$l$O%N!<%^%k%U%C%/$G$O$J$$$,!"(B
@code{add-hook}$B$H(B@code{remove-hook}$B$G%j%9%H$r07$($k!#(B
@pxref{Hooks}$B!#(B
@end defvar

@c Emacs 19 feature
@defvar local-write-file-hooks
@c This works just like @code{write-file-hooks}, but it is intended to be
@c made buffer-local in particular buffers, and used for hooks that pertain
@c to the file name or the way the buffer contents were obtained.
$B$3$l$O(B@code{write-file-hooks}$B$N$h$&$KF/$/$,!"(B
$BFCDj$N%P%C%U%!$K%P%C%U%!%m!<%+%k$K$9$k$h$&$K0U?^$7$F$"$j!"(B
$B%U%!%$%kL>$K4X$9$k%U%C%/$d%P%C%U%!FbMF$rF@$?J}K!$K4X$9$k(B
$B%U%C%/$H$7$F;H$o$l$k!#(B

@c The variable is marked as a permanent local, so that changing the major
@c mode does not alter a buffer-local value.  This is convenient for
@c packages that read ``file'' contents in special ways, and set up hooks
@c to save the data in a corresponding way.
$BJQ?t$O915WE*$K%P%C%U%!%m!<%+%k$H0u$,IU$$$F$$$k$N$G!"(B
$B%a%8%c!<%b!<%I$rJQ99$7$F$b%P%C%U%!%m!<%+%k$JCM$OJQ99$5$l$J$$!#(B
$B$3$l$O!"!X%U%!%$%k!Y$NFbMF$rFCJL$JJ}K!$GFI$_9~$_!"(B
$BBP1~$7$?J}K!$G%G!<%?$rJ]B8$9$k%U%C%/$r@_Dj$9$k$h$&$J%Q%C%1!<%8$K$OJXMx$G$"$k!#(B
@end defvar

@c Emacs 19 feature
@defvar write-contents-hooks
@c This works just like @code{write-file-hooks}, but it is intended for
@c hooks that pertain to the contents of the file, as opposed to hooks that
@c pertain to where the file came from.  Such hooks are usually set up by
@c major modes, as buffer-local bindings for this variable.
$B$3$NJQ?t$O(B@code{write-file-hooks}$B$N$h$&$KF/$/$,!"(B
$B%U%!%$%k$N>l=j$K4X$9$k%U%C%/$G$O$J$/!"(B
$B%U%!%$%k$NFbMF$K4X$9$k%U%C%/$G$"$k$H0U?^$5$l$F$$$k!#(B
$B$=$N$h$&$J%U%C%/$O!"$3$NJQ?t$N%P%C%U%!%m!<%+%k$JB+G{$H$7$F(B
$B%a%8%c!<%b!<%I$,DL>o@_Dj$9$k!#(B

@c This variable automatically becomes buffer-local whenever it is set;
@c switching to a new major mode always resets this variable.  When you use
@c @code{add-hooks} to add an element to this hook, you should @emph{not}
@c specify a non-@code{nil} @var{local} argument, since this variable is
@c used @emph{only} buffer-locally.
$B$3$NJQ?t$K@_Dj$9$k$H<+F0E*$K%P%C%U%!%m!<%+%k$K$J$k!#(B
$B$3$N%U%C%/$KMWAG$rDI2C$9$k$?$a$K(B@code{add-hooks}$B$r;H$&$H$-$K$O!"(B
$B0z?t(B@var{local}$B$K(B@code{nil}$B0J30$r;XDj$7(B@emph{$B$J$$(B}$B$3$H!#(B
$B$3$NJQ?t$O%P%C%U%!%m!<%+%k(B@emph{$B$N$_(B}$B$G$"$k$+$i$G$"$k!#(B
@end defvar

@c Emacs 19 feature
@defvar after-save-hook
@c This normal hook runs after a buffer has been saved in its visited file.
@c One use of this hook is in Fast Lock mode; it uses this hook to save the
@c highlighting information in a cache file.
$B$3$N%N!<%^%k%U%C%/$O!"%P%C%U%!$rK,Ld$7$?%U%!%$%k$K(B
$BJ]B8$7=*$($F$+$i<B9T$5$l$k!#(B
$B$3$N%U%C%/$NMQES$N(B1$B$D$O9bB.%m%C%/!J(Bfast-lock$B!K%b!<%I$G$"$k!#(B
$B$3$N%U%C%/$r;H$C$F6/D4I=<(>pJs$r%-%c%C%7%e%U%!%$%k$KJ]B8$9$k!#(B
@end defvar

@defvar file-precious-flag
@c If this variable is non-@code{nil}, then @code{save-buffer} protects
@c against I/O errors while saving by writing the new file to a temporary
@c name instead of the name it is supposed to have, and then renaming it to
@c the intended name after it is clear there are no errors.  This procedure
@c prevents problems such as a lack of disk space from resulting in an
@c invalid file.
$B$3$NJQ?t$,(B@code{nil}$B0J30$J$i$P!"(B
@code{save-buffer}$B$OJ]B8=hM}Cf$NF~=PNO%(%i!<$KHw$($FBP=h$9$k!#(B
$B$D$^$j!"L\E*$NL>A0$N%U%!%$%k$K$G$O$J$/0l;~E*$JL>A0$N?75,%U%!%$%k$K=q$-=P$7!"(B
$B%(%i!<$,$J$$$3$H$r3NG'$7$F$+$iL\E*$NL>A0$K2~L>$9$k!#(B
$B$3$l$K$h$j!"IT@5$J%U%!%$%k$K5/0x$9$kLdBj$+$i%G%#%9%/MFNL$NITB-$H$$$C$?(B
$BLdBj$r2sHr$G$-$k!#(B

@c As a side effect, backups are necessarily made by copying.  @xref{Rename
@c or Copy}.  Yet, at the same time, saving a precious file always breaks
@c all hard links between the file you save and other file names.
$BI{:nMQ$H$7$F!"%P%C%/%"%C%W$bI,A3E*$K%3%T!<$7$F9T$&!#(B
@pxref{Rename or Copy}$B!#(B
$B$=$l$HF1;~$K!"Bg;v$J!J(Bprecious$B!K%U%!%$%k$H$7$FJ]B8$9$k$H!"(B
$BFI<T$,J]B8$7$?%U%!%$%k$HJL$N%U%!%$%kL>$H$N$"$$$@$N(B
$B%O!<%I%j%s%/$r$D$M$K@Z$C$F$7$^$&!#(B

@c Some modes give this variable a non-@code{nil} buffer-local value
@c in particular buffers.
$BFCDj$N%P%C%U%!$G$O$3$NJQ?t$K(B@code{nil}$B0J30$N%P%C%U%!%m!<%+%k$JCM$r(B
$B;XDj$9$k%b!<%I$b$"$k!#(B
@end defvar

@defopt require-final-newline
@c This variable determines whether files may be written out that do
@c @emph{not} end with a newline.  If the value of the variable is
@c @code{t}, then @code{save-buffer} silently adds a newline at the end of
@c the file whenever the buffer being saved does not already end in one.
@c If the value of the variable is non-@code{nil}, but not @code{t}, then
@c @code{save-buffer} asks the user whether to add a newline each time the
@c case arises.
$B$3$NJQ?t$O!"2~9T$G=*$i(B@emph{$B$J$$(B}$B%U%!%$%k$r=q$-=P$9$+$I$&$+$r7hDj$9$k!#(B
$B$3$NJQ?t$NCM$,(B@code{t}$B$G$"$k$H!"(B@code{save-buffer}$B$O!"(B
$BJ]B8$9$k%P%C%U%!$,2~9T$G=*$C$F$$$J$$$HL[$C$F%U%!%$%k$NKvHx$K2~9T$rDI2C$9$k!#(B
$B$3$NJQ?t$NCM$,(B@code{t}$B$G$O$J$$(B@code{nil}$B0J30$G$"$k$H!"(B
@code{save-buffer}$B$O!"I,MW$J>lLL$G$O(B
$B2~9T$rDI2C$9$k$+$I$&$+%f!<%6!<$KLd$$9g$o$;$k!#(B

@c If the value of the variable is @code{nil}, then @code{save-buffer}
@c doesn't add newlines at all.  @code{nil} is the default value, but a few
@c major modes set it to @code{t} in particular buffers.
$B$3$NJQ?t$NCM$,(B@code{nil}$B$G$"$k$H!"(B@code{save-buffer}$B$O2~9T$rDI2C$7$J$$!#(B
$B%G%U%)%k%HCM$O(B@code{nil}$B$G$"$k$,!"FCDj$N%P%C%U%!$G$O(B@code{t}$B$K(B
$B@_Dj$9$k%a%8%c!<%b!<%I$b$"$k!#(B
@end defopt

@c   See also the function @code{set-visited-file-name} (@pxref{Buffer File
@c Name}).
$B4X?t(B@code{set-visited-file-name}$B!J(B@pxref{Buffer File Name}$B!K$b(B
$B;2>H$7$F$/$@$5$$!#(B

@node Reading from Files
@comment  node-name,  next,  previous,  up
@c @section Reading from Files
@section $B%U%!%$%k$NFI$_9~$_(B

@c   You can copy a file from the disk and insert it into a buffer
@c using the @code{insert-file-contents} function.  Don't use the user-level
@c command @code{insert-file} in a Lisp program, as that sets the mark.
$B4X?t(B@code{insert-file-contents}$B$r;H$C$F(B
$B%G%#%9%/$+$i%U%!%$%k$r%P%C%U%!$X%3%T!<$G$-$^$9!#(B
$B%f!<%6!<%l%Y%k$N%3%^%s%I(B@code{insert-file}$B$O%^!<%/$r@_Dj$9$k$N$G(B
Lisp$B%W%m%0%i%`$G$O;H$o$J$$$G$/$@$5$$!#(B

@defun insert-file-contents filename &optional visit beg end replace
@c This function inserts the contents of file @var{filename} into the
@c current buffer after point.  It returns a list of the absolute file name
@c and the length of the data inserted.  An error is signaled if
@c @var{filename} is not the name of a file that can be read.
$B$3$N4X?t$O!"%U%!%$%k(B@var{filename}$B$NFbMF$r%+%l%s%H%P%C%U%!$N(B
$B%]%$%s%H$N$&$7$m$KA^F~$9$k!#(B
$B@dBP%U%!%$%kL>$HA^F~$7$?%G!<%?$ND9$5$+$i@.$k%j%9%H$rJV$9!#(B
@var{filename}$B$,FI$_9~$a$k%U%!%$%k$NL>A0$G$J$$$H!"%(%i!<$rDLCN$9$k!#(B

@c The function @code{insert-file-contents} checks the file contents
@c against the defined file formats, and converts the file contents if
@c appropriate.  @xref{Format Conversion}.  It also calls the functions in
@c the list @code{after-insert-file-functions}; see @ref{Saving
@c Properties}.
$B4X?t(B@code{insert-file-contents}$B$O!"(B
$B%U%!%$%k$NFbMF$rDj5A:Q$_$N%U%!%$%k$N=q<0$HHf3S$7!"(B
$BI,MW$J$i$P%U%!%$%k$NFbMF$rJQ49$9$k!#(B
@pxref{Format Conversion}$B!#(B
$B%j%9%H(B@code{after-insert-file-functions}$B$N4X?t$b8F$S=P$9!#(B
@ref{Saving Properties}$B$r;2>H!#(B

@c If @var{visit} is non-@code{nil}, this function additionally marks the
@c buffer as unmodified and sets up various fields in the buffer so that it
@c is visiting the file @var{filename}: these include the buffer's visited
@c file name and its last save file modtime.  This feature is used by
@c @code{find-file-noselect} and you probably should not use it yourself.
@var{visit}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B$3$N4X?t$O%P%C%U%!$rL$JQ99$H0u$rIU$1!"(B
$B%U%!%$%k(B@var{filename}$B$rK,Ld$7$F$$$k%P%C%U%!$H$J$k$h$&$K(B
$B%P%C%U%!$N$5$^$6$^$JItJ,$r@_Dj$9$k!#(B
$B$3$l$K$O!"%P%C%U%!$,K,Ld$7$F$$$k%U%!%$%k$NL>A0!"%U%!%$%k99?7;~9o$r4^$`!#(B
$B$3$N5!G=$O(B@code{find-file-noselect}$B$G;H$o$l$F$*$j!"(B
$BFI<T<+?H$,;H$&$3$H$O$J$$$G$"$m$&!#(B

@c If @var{beg} and @var{end} are non-@code{nil}, they should be integers
@c specifying the portion of the file to insert.  In this case, @var{visit}
@c must be @code{nil}.  For example,
@var{beg}$B$H(B@var{end}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B$=$l$i$OA^F~$9$Y$-%U%!%$%k$NItJ,$r;XDj$9$k@0?t$G$"$k$3$H!#(B
$B$3$N>l9g!"(B@var{visit}$B$O(B@code{nil}$B$G$"$k$3$H!#(B
$B$?$H$($P!"(B

@example
(insert-file-contents filename nil 0 500)
@end example

@noindent
@c inserts the first 500 characters of a file.
$B$O%U%!%$%k$N:G=i$N(B500$BJ8;z$rA^F~$9$k!#(B

@c If the argument @var{replace} is non-@code{nil}, it means to replace the
@c contents of the buffer (actually, just the accessible portion) with the
@c contents of the file.  This is better than simply deleting the buffer
@c contents and inserting the whole file, because (1) it preserves some
@c marker positions and (2) it puts less data in the undo list.
$B0z?t(B@var{replace}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B%P%C%U%!$NFbMF!J<B:]$K$O;2>H2DG=$JItJ,$N$_!K$r(B
$B%U%!%$%k$NFbMF$GCV$-49$($k$3$H$r0UL#$9$k!#(B
$B$3$l$O!"C1=c$K%P%C%U%!$NFbMF$r:o=|$7$F$+$i%U%!%$%kA4BN$rA^F~$9$k$h$j(B
$B9%$^$7$$!#(B
$B$J$<$J$i!"!J(B1$B!K%^!<%+0LCV$rJ]B8$G$-$k>l9g$,$"$k!"(B
$B!J(B2$B!K%"%s%I%%%j%9%H$K$[$H$s$I%G!<%?$rF~$l$J$$!"$+$i$G$"$k!#(B

@c It is possible to read a special file (such as a FIFO or an I/O device)
@c with @code{insert-file-contents}, as long as @var{replace} and
@c @var{visit} are @code{nil}.
@var{replace}$B$H(B@var{visit}$B$,(B@code{nil}$B$G$"$k8B$j!"(B
@code{insert-file-contents}$B$G!J(BFIFO$B$dF~=PNOAuCV$J$I$N!K(B
$BFCJL$J%U%!%$%k$rFI$`$3$H$b2DG=$G$"$k!#(B
@end defun

@defun insert-file-contents-literally filename &optional visit beg end replace
@tindex insert-file-contents-literally
@c This function works like @code{insert-file-contents} except that it does
@c not do format decoding (@pxref{Format Conversion}), does not do
@c character code conversion (@pxref{Coding Systems}), does not run
@c @code{find-file-hooks}, does not perform automatic uncompression, and so
@c on.
$B$3$N4X?t$O(B@code{insert-file-contents}$B$N$h$&$KF0:n$9$k$,!"(B
$B=q<0$rJQ49$7$J$$!J(B@pxref{Format Conversion}$B!K!"(B
$BJ8;z%3!<%I$rJQ49$7$J$$!J(B@pxref{Coding Systems}$B!K!"(B
@code{find-file-hooks}$B$r<B9T$7$J$$!"<+F0E*$K2rE`$7$J$$$J$I$,0[$J$k!#(B
@end defun

@c If you want to pass a file name to another process so that another
@c program can read the file, use the function @code{file-local-copy}; see
@c @ref{Magic File Names}.
$BJL$N%W%m%0%i%`$,FI$a$k$h$&$K%U%!%$%kL>$rJL$N%W%m%;%9$KEO$9$K$O!"(B
$B4X?t(B@code{file-local-copy}$B$r;H$$$^$9!#(B
@ref{Magic File Names}$B$r;2>H$7$F$/$@$5$$!#(B

@node Writing to Files
@comment  node-name,  next,  previous,  up
@c @section Writing to Files
@section $B%U%!%$%k$X$N=q$-=P$7(B

@c   You can write the contents of a buffer, or part of a buffer, directly
@c to a file on disk using the @code{append-to-file} and
@c @code{write-region} functions.  Don't use these functions to write to
@c files that are being visited; that could cause confusion in the
@c mechanisms for visiting.
$B4X?t(B@code{append-to-file}$B$d(B@code{write-region}$B$r;H$C$F!"(B
$B%P%C%U%!$NFbMF$d$=$N0lIt$r%G%#%9%/>e$N%U%!%$%k$XD>@\=q$-=P$;$^$9!#(B
$BK,Ld$7$F$$$k%U%!%$%k$K$O!"$3$l$i$N4X?t$G=q$-=P$5$J$$$G$/$@$5$$!#(B
$BK,Ld$N5!9=$K:.Mp$r$-$?$9$3$H$,$"$j$^$9!#(B

@c @deffn Command append-to-file start end filename
@deffn $B%3%^%s%I(B append-to-file start end filename
@c This function appends the contents of the region delimited by
@c @var{start} and @var{end} in the current buffer to the end of file
@c @var{filename}.  If that file does not exist, it is created.  This
@c function returns @code{nil}.
$B$3$N4X?t$O!"%+%l%s%H%P%C%U%!$N(B@var{start}$B$+$i(B@var{end}$B$G(B
$B6h@Z$i$l$kNN0h$NFbMF$r%U%!%$%k(B@var{filename}$B$NKvHx$KDI2C$9$k!#(B
$BEv3:%U%!%$%k$,B8:_$7$J$1$l$P:n@.$9$k!#(B
$B$3$N4X?t$O(B@code{nil}$B$rJV$9!#(B

@c An error is signaled if @var{filename} specifies a nonwritable file,
@c or a nonexistent file in a directory where files cannot be created.
$B=q$-9~$a$J$$%U%!%$%k$r(B@var{filename}$B$K;XDj$7$?$j!"(B
$B%U%!%$%k$r:n@.$G$-$J$$%G%#%l%/%H%j>e$NB8:_$7$J$$%U%!%$%k$r(B
@var{filename}$B$K;XDj$9$k$H%(%i!<$rDLCN$9$k!#(B
@end deffn

@c @deffn Command write-region start end filename &optional append visit confirm
@deffn $B%3%^%s%I(B write-region start end filename &optional append visit confirm
@c This function writes the region delimited by @var{start} and @var{end}
@c in the current buffer into the file specified by @var{filename}.
$B$3$N4X?t$O!"%+%l%s%H%P%C%U%!$N(B@var{start}$B$+$i(B@var{end}$B$G(B
$B6h@Z$i$l$kNN0h$NFbMF$r(B@var{filename}$B$G;XDj$7$?%U%!%$%k$K=q$-=P$9!#(B

@c @c Emacs 19 feature
@c If @var{start} is a string, then @code{write-region} writes or appends
@c that string, rather than text from the buffer.
@var{start}$B$,J8;zNs$G$"$k$H!"(B
@code{write-region}$B$O%P%C%U%!$N%F%-%9%H$G$O$J$/(B
$B$=$NJ8;zNs$r=q$$$?$jDI2C$9$k!#(B

@c If @var{append} is non-@code{nil}, then the specified text is appended
@c to the existing file contents (if any).
@var{append}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B;XDj$7$?%F%-%9%H$r4{B8%U%!%$%k!J$,$"$l$P!K$NFbMF$KDI2C$9$k!#(B

@c If @var{confirm} is non-@code{nil}, then @code{write-region} asks
@c for confirmation if @var{filename} names an existing file.
@var{confirm}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
@var{filename}$B$,4{B8%U%!%$%k$NL>A0$G$"$k$H(B
@code{write-region}$B$O3NG'$r5a$a$k!#(B

@c If @var{visit} is @code{t}, then Emacs establishes an association
@c between the buffer and the file: the buffer is then visiting that file.
@c It also sets the last file modification time for the current buffer to
@c @var{filename}'s modtime, and marks the buffer as not modified.  This
@c feature is used by @code{save-buffer}, but you probably should not use
@c it yourself.
@var{visit}$B$,(B@code{t}$B$G$"$k$H!"(B
Emacs$B$O%P%C%U%!$H%U%!%$%k$NBP1~$r3NN)$9$k!#(B
$B$D$^$j!"%P%C%U%!$O$=$N%U%!%$%k$rK,Ld$7$F$$$k$3$H$K$J$k!#(B
$B$5$i$K!"%+%l%s%H%P%C%U%!$N:G=*%U%!%$%k99?7;~9o$r(B
@var{filename}$B$N99?7;~9o$K$7!"(B
$B%P%C%U%!$K$OL$JQ99$H0u$rIU$1$k!#(B
$B$3$N5!G=$O(B@code{save-buffer}$B$,;H$C$F$$$k$,!"(B
$BFI<T<+?H$,;H$&$3$H$O$J$$$G$"$m$&!#(B

@c @c Emacs 19 feature
@c If @var{visit} is a string, it specifies the file name to visit.  This
@c way, you can write the data to one file (@var{filename}) while recording
@c the buffer as visiting another file (@var{visit}).  The argument
@c @var{visit} is used in the echo area message and also for file locking;
@c @var{visit} is stored in @code{buffer-file-name}.  This feature is used
@c to implement @code{file-precious-flag}; don't use it yourself unless you
@c really know what you're doing.
@var{visit}$B$,J8;zNs$G$"$k$H!"K,Ld$9$k%U%!%$%k$NL>A0$r;XDj$9$k!#(B
$B$3$N$h$&$K$7$F!"%G!<%?$r(B1$B$D$N%U%!%$%k!J(B@var{filename}$B!K$K=q$-=P$90lJ}$G!"(B
$B%P%C%U%!$OJL$N%U%!%$%k!J(B@var{visit}$B!K$rK,Ld$7$F$$$k$H@_Dj$G$-$k!#(B
$B0z?t(B@var{visit}$B$O%(%3!<NN0h$N%a%C%;!<%8$K;H$o$l!"(B
$B%U%!%$%k$N%m%C%/$K$b;H$o$l$k!#(B
@var{visit}$B$O(B@code{buffer-file-name}$B$KJ]B8$5$l$k!#(B
$B$3$N5!G=$O(B@code{file-precious-flag}$B$N<BAu$K;H$o$l$F$$$k$,!"(B
$BFI<T$O!"$J$K$r$7$F$$$k$+M}2r$G$-$J$$8B$j!"$3$N5!G=$r;H$o$J$$$3$H!#(B

@c The function @code{write-region} converts the data which it writes to
@c the appropriate file formats specified by @code{buffer-file-format}.
@c @xref{Format Conversion}.  It also calls the functions in the list
@c @code{write-region-annotate-functions}; see @ref{Saving Properties}.
$B4X?t(B@code{write-region}$B$O!"=q$-=P$9%G!<%?$r(B
@code{buffer-file-format}$B$G;XDj$5$l$kE,@Z$J%U%!%$%k=q<0$KJQ49$9$k!#(B
@pxref{Format Conversion}$B!#(B
$B$5$i$K!"%j%9%H(B@code{write-region-annotate-functions}$B$N4X?t$b8F$S=P$9!#(B
@ref{Saving Properties}$B$r;2>H!#(B

@c Normally, @code{write-region} displays the message @samp{Wrote
@c @var{filename}} in the echo area.  If @var{visit} is neither @code{t}
@c nor @code{nil} nor a string, then this message is inhibited.  This
@c feature is useful for programs that use files for internal purposes,
@c files that the user does not need to know about.
$BDL>o!"(B@code{write-region}$B$O%(%3!<NN0h$K%a%C%;!<%8(B
@samp{Wrote @var{filename}}$B$rI=<($9$k!#(B
@var{visit}$B$,(B@code{t}$B$G$b(B@code{nil}$B$G$bJ8;zNs$G$b$J$$$H!"(B
$B$3$N%a%C%;!<%8$OI=<($7$J$$!#(B
$B$3$N5!G=$O!"%f!<%6!<$,CN$kI,MW$N$J$$(B
$BFbItL\E*$K%U%!%$%k$r;H$&%W%m%0%i%`$KM-MQ$G$"$k!#(B
@end deffn

@defmac with-temp-file file body...
@tindex with-temp-file
@c The @code{with-temp-file} macro evaluates the @var{body} forms with a
@c temporary buffer as the current buffer; then, at the end, it writes the
@c buffer contents into file @var{file}.  It kills the temporary buffer
@c when finished, restoring the buffer that was current before the
@c @code{with-temp-file} form.  Then it returns the value of the last form
@c in @var{body}.
$B%^%/%m(B@code{with-temp-file}$B$O!"0l;~E*$J%P%C%U%!$r%+%l%s%H%P%C%U%!$H$7$F(B
$B%U%)!<%`(B@var{body}$B$rI>2A$9$k!#(B
$B$=$7$F:G8e$K%P%C%U%!$NFbMF$r%U%!%$%k(B@var{file}$B$K=q$-=P$9!#(B
$B=*N;$9$k$H0l;~E*$J%P%C%U%!$r:o=|$7!"(B
$B%U%)!<%`(B@code{with-temp-file}$B$N$^$($K%+%l%s%H%P%C%U%!$G$"$C$?%P%C%U%!$KLa$k!#(B
@var{body}$B$N:G8e$N%U%)!<%`$NCM$rJV$9!#(B

@c The current buffer is restored even in case of an abnormal exit via
@c @code{throw} or error (@pxref{Nonlocal Exits}).
@code{throw}$B$d%(%i!<$K$h$k0[>o=*N;!J(B@pxref{Nonlocal Exits}$B!K$G$"$C$F$b(B
$B%+%l%s%H%P%C%U%!$KLa$k!#(B

@c See also @code{with-temp-buffer} in @ref{Current Buffer}.
@ref{Current Buffer}$B$N(B@code{with-temp-buffer}$B$b;2>H!#(B
@end defmac

@node File Locks
@c @section File Locks
@section $B%U%!%$%k%m%C%/(B
@c @cindex file locks
@cindex $B%U%!%$%k%m%C%/(B
@cindex $B%m%C%/!"%U%!%$%k(B

@c   When two users edit the same file at the same time, they are likely to
@c interfere with each other.  Emacs tries to prevent this situation from
@c arising by recording a @dfn{file lock} when a file is being modified.
@c Emacs can then detect the first attempt to modify a buffer visiting a
@c file that is locked by another Emacs job, and ask the user what to do.
2$B?M$N%f!<%6!<$,F1;~$KF1$8%U%!%$%k$rJT=8$9$k$H!"8_$$$K43>D$79g$$$^$9!#(B
Emacs$B$O!"%U%!%$%k$,JQ99$5$l$k$H(B@dfn{$B%U%!%$%k%m%C%/(B}$B!J(Bfile lock$B!K$r(B
$B5-O?$9$k$3$H$G!"$3$N$h$&$J>u67$,H/@8$7$J$$$h$&$KEX$a$^$9!#(B
$B$9$k$H!"(BEmacs$B$OJL$N(BEmacs$B$,%m%C%/$7$F$$$k%U%!%$%k$rK,Ld$7$?(B
$B%P%C%U%!$rJQ99$7$h$&$H$9$k:G=i$N;n$_$r8!=P$G$-!"(B
$B%f!<%6!<$K$I$&$9$Y$-$+$rLd$$9g$o$;$^$9!#(B

@c   File locks are not completely reliable when multiple machines can
@c share file systems.  When file locks do not work, it is possible for two
@c users to make changes simultaneously, but Emacs can still warn the user
@c who saves second.  Also, the detection of modification of a buffer
@c visiting a file changed on disk catches some cases of simultaneous
@c editing; see @ref{Modification Time}.
$BJ#?t$N7W;;5!$,%U%!%$%k%7%9%F%`$r6&M-$7$F$$$k>l9g$K$O!"(B
$B%U%!%$%k%m%C%/$K$O40A4$J?.Mj@-$O$"$j$^$;$s!#(B
$B%U%!%$%k%m%C%/$,F/$+$J$$$H!"(B
2$B?M$N%f!<%6!<$,F1;~$KJQ99$9$k2DG=@-$,$"$j$^$9$,!"(B
$B$=$l$G$b!"(BEmacs$B$O(B2$BHVL\$KJ]B8$7$?%f!<%6!<$K7Y9p$G$-$^$9!#(B
$B$^$?!"%G%#%9%/>e$GJQ99$5$l$?%U%!%$%k$rK,Ld$7$F$$$k%P%C%U%!$NJQ99$r(B
$B8!=P$9$k$3$H$G!"F1;~JT=8$N$"$k>lLL$rJaB*$G$-$^$9!#(B
@ref{Modification Time}$B$r;2>H$7$F$/$@$5$$!#(B

@defun file-locked-p filename
@c This function returns @code{nil} if the file @var{filename} is not
@c locked.  It returns @code{t} if it is locked by this Emacs process, and
@c it returns the name of the user who has locked it if it is locked by
@c some other job.
$B%U%!%$%k(B@var{filename}$B$,%m%C%/$5$l$F$$$J$1$l$P!"$3$N4X?t$O(B@code{nil}$B$rJV$9!#(B
$B$3$N(BEmacs$B%W%m%;%9$,%m%C%/$7$F$$$k$H$-$K$O(B@code{t}$B$rJV$9!#(B
$BB>$N(BEmacs$B$,%m%C%/$7$F$$$k>l9g$K$O!"%m%C%/$7$F$$$k%f!<%6!<$NL>A0$rJV$9!#(B

@example
@group
(file-locked-p "foo")
     @result{} nil
@end group
@end example
@end defun

@defun lock-buffer &optional filename
@c   This function locks the file @var{filename}, if the current buffer is
@c modified.  The argument @var{filename} defaults to the current buffer's
@c visited file.  Nothing is done if the current buffer is not visiting a
@c file, or is not modified.
$B$3$N4X?t$O!"%+%l%s%H%P%C%U%!$,JQ99$5$l$F$$$l$P(B
$B%U%!%$%k(B@var{filename}$B$r%m%C%/$9$k!#(B
$B0z?t(B@var{filename}$B$N%G%U%)%k%H$O!"(B
$B%+%l%s%H%P%C%U%!$GK,Ld$7$F$$$k%U%!%$%k$G$"$k!#(B
$B%+%l%s%H%P%C%U%!$,%U%!%$%k$rK,Ld$7$F$$$J$+$C$?$j!"(B
$BL$JQ99$J$i$P$J$K$b$7$J$$!#(B
@end defun

@defun unlock-buffer
@c This function unlocks the file being visited in the current buffer,
@c if the buffer is modified.  If the buffer is not modified, then
@c the file should not be locked, so this function does nothing.  It also
@c does nothing if the current buffer is not visiting a file.
$B$3$N4X?t$O!"%P%C%U%!$,JQ99$5$l$F$$$l$P!"(B
$B%+%l%s%H%P%C%U%!$GK,Ld$7$F$$$k%U%!%$%k$N%m%C%/$r2r=|$9$k!#(B
$B%P%C%U%!$,L$JQ99$J$i$P%U%!%$%k$r%m%C%/$7$F$$$J$$$O$:$G$"$j!"(B
$B$3$N4X?t$O$J$K$b$7$J$$!#(B
$B%+%l%s%H%P%C%U%!$,%U%!%$%k$rK,Ld$7$F$$$J$1$l$P!"(B
$B$d$O$j$J$K$b$7$J$$!#(B
@end defun

@defun ask-user-about-lock file other-user
@c This function is called when the user tries to modify @var{file}, but it
@c is locked by another user named @var{other-user}.  The default
@c definition of this function asks the user to say what to do.  The value
@c this function returns determines what Emacs does next:
$B$3$N4X?t$O!"JL$N%f!<%6!<(B@var{other-user}$B$,%m%C%/$7$F$$$k(B
$B%U%!%$%k(B@var{file}$B$r%f!<%6!<$,JQ99$7$h$&$H$7$?$H$-$K8F$S=P$5$l$k!#(B
$B$3$N4X?t$N%G%U%)%k%H$NDj5A$O!"%f!<%6!<$K$J$K$r$9$Y$-$+(B
$BLd$$9g$o$;$k$3$H$G$"$k!#(B
$B$3$N4X?t$NLa$jCM$,(BEmacs$B$N$D$.$NF0:n$r7hDj$9$k!#(B

@itemize @bullet
@item
@c A value of @code{t} says to grab the lock on the file.  Then
@c this user may edit the file and @var{other-user} loses the lock.
$BCM$,(B@code{t}$B$G$"$k$H!"%U%!%$%k$N%m%C%/$r<hF@$9$k$3$H$r0UL#$9$k!#(B
$B$9$k$H!"$3$N%f!<%6!<$O%U%!%$%k$rJT=8$G$-!"(B
$BJL$N%f!<%6!<(B@var{other-user}$B$O%m%C%/$r<:$&!#(B

@item
@c A value of @code{nil} says to ignore the lock and let this
@c user edit the file anyway.
$BCM$,(B@code{nil}$B$G$"$k$H!"%m%C%/$rL5;k$7$F(B
$B$H$K$+$/%f!<%6!<$K%U%!%$%k$NJT=8$r5v$9!#(B

@item
@kindex file-locked
@c This function may instead signal a @code{file-locked} error, in which
@c case the change that the user was about to make does not take place.
$B$3$N4X?t$O%(%i!<(B@code{file-locked}$B$rDLCN$9$k!#(B
$B$3$N>l9g!"%f!<%6!<$,9T$*$&$H$7$F$$$?JQ99$O9T$o$l$J$$!#(B

@c The error message for this error looks like this:
$B$3$N%(%i!<$N%(%i!<%a%C%;!<%8$O$D$.$N$h$&$G$"$k!#(B

@example
@error{} File is locked: @var{file} @var{other-user}
@end example

@noindent
@c where @code{file} is the name of the file and @var{other-user} is the
@c name of the user who has locked the file.
$B$3$3$G!"(B@code{file}$B$O%U%!%$%kL>$G$"$j!"(B
@var{other-user}$B$O$=$N%U%!%$%k$r%m%C%/$7$F$$$k%f!<%6!<L>$G$"$k!#(B
@end itemize

@c If you wish, you can replace the @code{ask-user-about-lock} function
@c with your own version that makes the decision in another way.  The code
@c for its usual definition is in @file{userlock.el}.
$BFI<T$O!"4X?t(B@code{ask-user-about-lock}$B$r(B
$BJL$NJ}K!$G7hDj$9$kFI<TFH<+$N$b$N$KCV$-49$($F$b$h$$!#(B
$BDL>o$NDj5A$KBP1~$7$?%3!<%I$O(B@file{userlock.el}$B$K$"$k!#(B
@end defun

@node Information about Files
@c @section Information about Files
@section $B%U%!%$%k$K4X$9$k>pJs(B

@c   The functions described in this section all operate on strings that
@c designate file names.  All the functions have names that begin with the
@c word @samp{file}.  These functions all return information about actual
@c files or directories, so their arguments must all exist as actual files
@c or directories unless otherwise noted.
$BK\@a$K=R$Y$k4X?t$O$9$Y$F!"%U%!%$%kL>$rI=$9J8;zNs$K:nMQ$7$^$9!#(B
$B$9$Y$F$N4X?t$NL>A0$OC18l(B@samp{file}$B$G;O$^$j!"(B
$B$=$l$i$N0z?t$O!"FC$KCG$i$J$$$+$.$j!"(B
$B4{B8$N%U%!%$%k$d%G%#%l%/%H%j$G$"$kI,MW$,$"$j$^$9!#(B

@menu
* Testing Accessibility::   Is a given file readable?  Writable?
* Kinds of Files::          Is it a directory?  A symbolic link?
* Truenames::		    Eliminating symbolic links from a file name.
* File Attributes::         How large is it?  Any other names?  Etc.
@end menu

@node Testing Accessibility
@comment  node-name,  next,  previous,  up
@c @subsection Testing Accessibility
@subsection $B;2>H2DG=@-$N8!::(B
@c @cindex accessibility of a file
@c @cindex file accessibility
@cindex $B%U%!%$%k$N;2>H2DG=@-(B
@cindex $B;2>H2DG=@-!"%U%!%$%k(B

@c   These functions test for permission to access a file in specific ways.
$B$3$l$i$N4X?t$O!"FCJL$JJ}K!$G%U%!%$%k;2>H$N%Q!<%_%C%7%g%s$r8!::$7$^$9!#(B

@defun file-exists-p filename
@c This function returns @code{t} if a file named @var{filename} appears
@c to exist.  This does not mean you can necessarily read the file, only
@c that you can find out its attributes.  (On Unix, this is true if the
@c file exists and you have execute permission on the containing
@c directories, regardless of the protection of the file itself.)
$B%U%!%$%k(B@var{filename}$B$,B8:_$9$l$P!"$3$N4X?t$O(B@code{t}$B$rJV$9!#(B
$B$3$l$OI,$:$7$b%U%!%$%k$rFI$a$k$3$H$O0UL#$;$:!"(B
$BC1$K%U%!%$%k$NB0@-$rD4$Y$i$l$k$@$1$G$"$k!#(B
$B!J(BUNIX$B$G$O!"%U%!%$%k$,B8:_$7!"$+$D!"(B
$B$=$l$r<}$a$?%G%#%l%/%H%j$KBP$9$k<B9T%Q!<%_%C%7%g%s$,$"$l$P!"(B
$B%U%!%$%k<+BN$N%Q!<%_%C%7%g%s$K4X78$J$/$3$N$h$&$K$J$k!#!K(B

@c If the file does not exist, or if fascist access control policies
@c prevent you from finding the attributes of the file, this function
@c returns @code{nil}.
$B%U%!%$%k$,B8:_$7$J$+$C$?$j!"%U%!%$%k$NB0@-$rC5$98"8B$,$J$1$l$P!"(B
$B$3$N4X?t$O(B@code{nil}$B$rJV$9!#(B
@end defun

@defun file-readable-p filename
@c This function returns @code{t} if a file named @var{filename} exists
@c and you can read it.  It returns @code{nil} otherwise.
$B%U%!%$%k(B@var{filename}$B$,B8:_$7$=$l$rFI$`$3$H$,$G$-$k$J$i$P!"(B
$B$3$N4X?t$O(B@code{t}$B$rJV$9!#(B
$B$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B

@example
@group
(file-readable-p "files.texi")
     @result{} t
@end group
@group
(file-exists-p "/usr/spool/mqueue")
     @result{} t
@end group
@group
(file-readable-p "/usr/spool/mqueue")
     @result{} nil
@end group
@end example
@end defun

@c Emacs 19 feature
@defun file-executable-p filename
@c This function returns @code{t} if a file named @var{filename} exists and
@c you can execute it.  It returns @code{nil} otherwise.  If the file is a
@c directory, execute permission means you can check the existence and
@c attributes of files inside the directory, and open those files if their
@c modes permit.
$B%U%!%$%k(B@var{filename}$B$,B8:_$7$=$l$r<B9T$G$-$k$J$i$P!"(B
$B$3$N4X?t$O(B@code{t}$B$rJV$9!#(B
$B$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
$B%U%!%$%k$,%G%#%l%/%H%j$G$"$k>l9g!"<B9T%Q!<%_%C%7%g%s$O!"(B
$B%G%#%l%/%H%jFb$N%U%!%$%k$NB8:_$d$=$NB0@-$r8!::$G$-!"(B
$B$=$l$i$N%U%!%$%k$N%b!<%I$,5v$;$P%*!<%W%s$G$-$k$3$H$r0UL#$9$k!#(B
@end defun

@defun file-writable-p filename
@c This function returns @code{t} if the file @var{filename} can be written
@c or created by you, and @code{nil} otherwise.  A file is writable if the
@c file exists and you can write it.  It is creatable if it does not exist,
@c but the specified directory does exist and you can write in that
@c directory.
$B%U%!%$%k(B@var{filename}$B$K=q$-=P$7$?$j:n@.$G$-$k$J$i$P!"(B
$B$3$N4X?t$O(B@code{t}$B$rJV$7!"$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
$B%U%!%$%k$K=q$-=P$;$k$N$O!"%U%!%$%k$,B8:_$7=q$1$k>l9g$G$"$k!#(B
$B:n@.$G$-$k$N$O!"%U%!%$%k$OB8:_$7$J$$$,(B
$B;XDj$7$?%G%#%l%/%H%j$,B8:_$7$=$N%G%#%l%/%H%j$K=q$1$k>l9g$G$"$k!#(B

@c In the third example below, @file{foo} is not writable because the
@c parent directory does not exist, even though the user could create such
@c a directory.
$B0J2<$N(B3$BHVL\$NNc$G$O!"(B@file{foo}$B$N?F%G%#%l%/%H%j$,B8:_$7$J$$$N$G!"(B
$B$?$H$(%G%#%l%/%H%j$r:n@.$G$-$k$H$7$F$b(B@file{foo}$B$O=q$1$J$$!#(B

@example
@group
(file-writable-p "~/foo")
     @result{} t
@end group
@group
(file-writable-p "/foo")
     @result{} nil
@end group
@group
(file-writable-p "~/no-such-dir/foo")
     @result{} nil
@end group
@end example
@end defun

@c Emacs 19 feature
@defun file-accessible-directory-p dirname
@c This function returns @code{t} if you have permission to open existing
@c files in the directory whose name as a file is @var{dirname}; otherwise
@c (or if there is no such directory), it returns @code{nil}.  The value
@c of @var{dirname} may be either a directory name or the file name of a
@c file which is a directory.
$B%G%#%l%/%H%j(B@var{dirname}$B$N4{B8%U%!%$%k$r%*!<%W%s$9$k%Q!<%_%C%7%g%s$,$"$l$P!"(B
$B$3$N4X?t$O(B@code{t}$B$rJV$9!#(B
$B$5$b$J$1$l$P!J$"$k$$$OEv3:%G%#%l%/%H%j$,B8:_$7$J$1$l$P!K(B@code{nil}$B$rJV$9!#(B
@var{dirname}$B$NCM$O%G%#%l%/%H%jL>$G$"$k!#(B

@c Example: after the following,
$BNc!'(B@code{ }$B$D$.$NNc$G$O!"(B

@example
(file-accessible-directory-p "/foo")
     @result{} nil
@end example

@noindent
@c we can deduce that any attempt to read a file in @file{/foo/} will
@c give an error.
$B$+$i!"(B@file{/foo/}$BFb$N%U%!%$%k$rFI$b$&$H$9$k$H(B
$B%(%i!<$K$J$k$H?dO@$G$-$k!#(B
@end defun

@defun access-file filename string
@tindex access-file
@c This function opens file @var{filename} for reading, then closes it and
@c returns @code{nil}.  However, if the open fails, it signals an error
@c using @var{string} as the error message text.
$B$3$N4X?t$O!"%U%!%$%k(B@var{filename}$B$rFI$`$?$a$K%*!<%W%s$7!"(B
$B%/%m!<%:$7$F$+$i(B@code{nil}$B$rJV$9!#(B
$B$7$+$7!"%*!<%W%s$K<:GT$9$k$H(B@var{string}$B$r%(%i!<%a%C%;!<%8$N%F%-%9%H$H$7$?(B
$B%(%i!<$rDLCN$9$k!#(B
@end defun

@defun file-ownership-preserved-p filename
@c This function returns @code{t} if deleting the file @var{filename} and
@c then creating it anew would keep the file's owner unchanged.
$B$b$7%U%!%$%k(B@var{filename}$B$r:o=|$7$F2~$a$F:n@.$7$F$b(B
$B%U%!%$%k$N=jM-<T$,JQ99$5$l$J$1$l$P!"$3$N4X?t$O(B@code{t}$B$rJV$9!#(B
@end defun

@defun file-newer-than-file-p filename1 filename2
@c @cindex file age
@c @cindex file modification time
@cindex $B%U%!%$%k$N8E$5(B
@cindex $B%U%!%$%k99?7;~9o(B
@c This function returns @code{t} if the file @var{filename1} is
@c newer than file @var{filename2}.  If @var{filename1} does not
@c exist, it returns @code{nil}.  If @var{filename2} does not exist,
@c it returns @code{t}.
$B%U%!%$%k(B@var{filename1}$B$,(B@var{filename2}$B$h$j?7$7$1$l$P!"(B
$B$3$N4X?t$O(B@code{t}$B$rJV$9!#(B
@var{filename1}$B$,B8:_$7$J$1$l$P(B@code{nil}$B$rJV$9!#(B
@var{filename2}$B$,B8:_$7$J$1$l$P(B@code{t}$B$rJV$9!#(B

@c In the following example, assume that the file @file{aug-19} was written
@c on the 19th, @file{aug-20} was written on the 20th, and the file
@c @file{no-file} doesn't exist at all.
$B0J2<$NNc$G!"%U%!%$%k(B@file{aug-19}$B$O(B19$BF|$K=q$+$l!"(B
$B%U%!%$%k(B@file{aug-20}$B$O(B20$BF|$K=q$+$l!"(B
$B%U%!%$%k(B@file{no-file}$B$OB8:_$7$J$$$H2>Dj$9$k!#(B

@example
@group
(file-newer-than-file-p "aug-19" "aug-20")
     @result{} nil
@end group
@group
(file-newer-than-file-p "aug-20" "aug-19")
     @result{} t
@end group
@group
(file-newer-than-file-p "aug-19" "no-file")
     @result{} t
@end group
@group
(file-newer-than-file-p "no-file" "aug-19")
     @result{} nil
@end group
@end example

@c You can use @code{file-attributes} to get a file's last modification
@c time as a list of two numbers.  @xref{File Attributes}.
@code{file-attributes}$B$r;H$C$F!"(B
2$B$D$N?t$+$i@.$k%j%9%H$H$7$F%U%!%$%k$N:G=*99?7;~9o$r<hF@$G$-$k!#(B
@pxref{File Attributes}$B!#(B
@end defun

@node Kinds of Files
@comment  node-name,  next,  previous,  up
@c @subsection Distinguishing Kinds of Files
@subsection $B%U%!%$%k$N<oN`$N6hJL(B

@c   This section describes how to distinguish various kinds of files, such
@c as directories, symbolic links, and ordinary files.
$BK\@a$G$O$5$^$6$^$J<oN`$N%U%!%$%k!"$D$^$j!"(B
$B%G%#%l%/%H%j!"%7%s%\%j%C%/%j%s%/!"IaDL$N%U%!%$%k$r6hJL$9$kJ}K!$r(B
$B@bL@$7$^$9!#(B

@defun file-symlink-p filename
@c @cindex file symbolic links
@cindex $B%7%s%\%j%C%/%j%s%/!"%U%!%$%k(B
@cindex $B%U%!%$%k$N%7%s%\%j%C%/%j%s%/(B
@c If the file @var{filename} is a symbolic link, the @code{file-symlink-p}
@c function returns the file name to which it is linked.  This may be the
@c name of a text file, a directory, or even another symbolic link, or it
@c may be a nonexistent file name.
$B%U%!%$%k(B@var{filename}$B$,%7%s%\%j%C%/%j%s%/$G$"$k$H!"(B
$B4X?t(B@code{file-symlink-p}$B$OEv3:%j%s%/$,;X$9%U%!%$%k$NL>A0$rJV$9!#(B
$B$3$l$O!"%F%-%9%H%U%!%$%k!"%G%#%l%/%H%j!"JL$N%7%s%\%j%C%/%j%s%/!"(B
$BB8:_$7$J$$%U%!%$%k$NL>A0$N$$$:$l$+$G$"$k!#(B

@c If the file @var{filename} is not a symbolic link (or there is no such file),
@c @code{file-symlink-p} returns @code{nil}.  
$B%U%!%$%k(B@var{filename}$B$,%7%s%\%j%C%/%j%s%/$G$J$$(B
$B!J$"$k$$$OEv3:%U%!%$%k$,B8:_$7$J$$!K>l9g!"(B
@code{file-symlink-p}$B$O(B@code{nil}$B$rJV$9!#(B

@example
@group
(file-symlink-p "foo")
     @result{} nil
@end group
@group
(file-symlink-p "sym-link")
     @result{} "foo"
@end group
@group
(file-symlink-p "sym-link2")
     @result{} "sym-link"
@end group
@group
(file-symlink-p "/bin")
     @result{} "/pub/bin"
@end group
@end example

@c !!! file-symlink-p: should show output of ls -l for comparison
@end defun

@defun file-directory-p filename
@c This function returns @code{t} if @var{filename} is the name of an
@c existing directory, @code{nil} otherwise.
$B%U%!%$%k(B@var{filename}$B$,4{B8%G%#%l%/%H%j$NL>A0$G$"$k$H(B@code{t}$B$rJV$7!"(B
$B$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B

@example
@group
(file-directory-p "~rms")
     @result{} t
@end group
@group
(file-directory-p "~rms/lewis/files.texi")
     @result{} nil
@end group
@group
(file-directory-p "~rms/lewis/no-such-file")
     @result{} nil
@end group
@group
(file-directory-p "$HOME")
     @result{} nil
@end group
@group
(file-directory-p
 (substitute-in-file-name "$HOME"))
     @result{} t
@end group
@end example
@end defun

@defun file-regular-p filename
@c This function returns @code{t} if the file @var{filename} exists and is
@c a regular file (not a directory, symbolic link, named pipe, terminal, or
@c other I/O device).
$B%U%!%$%k(B@var{filename}$B$,B8:_$7$=$l$,IaDL$N%U%!%$%k(B
$B!J%G%#%l%/%H%j$G$b%7%s%\%j%C%/%j%s%/$G$bL>A0IU$-%Q%$%W$G$b(B
$BC<Kv$G$b$=$NB>$NF~=PNOAuCV$G$b$J$$!K$G$"$l$P!"(B
$B$3$N4X?t$O(B@code{t}$B$rJV$9!#(B
@end defun

@node Truenames
@c @subsection Truenames
@subsection $B<BL>(B
@c @cindex truename (of file)
@cindex $B<BL>!J%U%!%$%k!K(B
@cindex $B%U%!%$%k$N<BL>(B

@c @c Emacs 19 features
@c   The @dfn{truename} of a file is the name that you get by following
@c symbolic links until none remain, then simplifying away @samp{.}@: and
@c @samp{..}@: appearing as components.  Strictly speaking, a file need not
@c have a unique truename; the number of distinct truenames a file has is
@c equal to the number of hard links to the file.  However, truenames are
@c useful because they eliminate symbolic links as a cause of name
@c variation.
$B%U%!%$%k$N(B@dfn{$B<BL>(B}$B!J(Btruename$B!K$H$O!"(B
$B%7%s%\%j%C%/%j%s%/$r$9$Y$FC)$j?T$/$7$F$+$i!"(B
$BMWAG$H$7$F8=$l$k(B@samp{.}@: $B$d(B@samp{..}@: $B$r4JN,2=$7$FF@$i$l$kL>A0$G$9!#(B
$B87L)$K$$$($P!"%U%!%$%k$,0l0U$N<BL>$r;}$DI,MW$O$"$j$^$;$s!#(B
$B%U%!%$%k$N0[$J$k<BL>$N8D?t$O!"Ev3:%U%!%$%k$KBP$9$k%O!<%I%j%s%/$N8D?t$K(B
$BEy$7$$$N$G$9!#(B
$B$=$l$G$b!"<BL>$O%7%s%\%j%C%/%j%s%/$K$h$kL>A0$NJQF0$r<h$j=|$/$?$a!"(B
$B<BL>$OM-MQ$G$9!#(B

@defun file-truename filename
@c The function @code{file-truename} returns the true name of the file
@c @var{filename}.  This is the name that you get by following symbolic
@c links until none remain.  The argument must be an absolute file name.
$B4X?t(B@code{file-truename}$B$O%U%!%$%k(B@var{filename}$B$N<BL>$rJV$9!#(B
$B$3$l$O%7%s%\%j%C%/%j%s%/$r$9$Y$FC)$j?T$/$7$FF@$i$l$kL>A0$G$"$k!#(B
$B0z?t$O@dBP%U%!%$%kL>$G$"$k$3$H!#(B
@end defun

@c   @xref{Buffer File Name}, for related information.
$B4XO">pJs$K$D$$$F$O!"(B@xref{Buffer File Name}$B!#(B

@node File Attributes
@comment  node-name,  next,  previous,  up
@c @subsection Other Information about Files
@subsection $B%U%!%$%k$K4X$9$kB>$N>pJs(B

@c   This section describes the functions for getting detailed information
@c about a file, other than its contents.  This information includes the
@c mode bits that control access permission, the owner and group numbers,
@c the number of names, the inode number, the size, and the times of access
@c and modification.
$BK\@a$G$O!"%U%!%$%k$NFbMF0J30$N>\$7$$>pJs$rF@$k$?$a$N4X?t$r@bL@$7$^$9!#(B
$B$3$N>pJs$K$O!";2>H%Q!<%_%C%7%g%s$r@)8f$9$k%b!<%I%S%C%H!"(B
$B=jM-<T$H%0%k!<%W$NHV9f!"L>A0$N8D?t!"(Bi$B%N!<%IHV9f!"%5%$%:!"(B
$B;2>H;~9o$H99?7;~9o$,4^$^$l$^$9!#(B

@defun file-modes filename
@c @cindex permission
@c @cindex file attributes
@cindex $B%Q!<%_%C%7%g%s(B
@cindex $B%U%!%$%k$NB0@-(B
@c This function returns the mode bits of @var{filename}, as an integer.
@c The mode bits are also called the file permissions, and they specify
@c access control in the usual Unix fashion.  If the low-order bit is 1,
@c then the file is executable by all users, if the second-lowest-order bit
@c is 1, then the file is writable by all users, etc.
$B$3$N4X?t$O(B@var{filename}$B$N%b!<%I%S%C%H$r@0?t$GJV$9!#(B
$B%b!<%I%S%C%H$O%U%!%$%k$N%Q!<%_%C%7%g%s$H$b8F$P$l!"(B
UNIX$BN.$N;2>H@)8f$r;XDj$9$k!#(B
$B:G2<0L%S%C%H$,(B1$B$G$"$k$H!"Ev3:%U%!%$%k$O$9$Y$F$N%f!<%6!<$,<B9T$G$-!"(B
2$BHVL\$N2<0L%S%C%H$,(B1$B$G$"$k$H!"Ev3:%U%!%$%k$O$9$Y$F$N%f!<%6!<$,=q$1$k(B
$B$H$$$C$?6q9g$G$"$k!#(B

@c The highest value returnable is 4095 (7777 octal), meaning that
@c everyone has read, write, and execute permission, that the @sc{suid} bit
@c is set for both others and group, and that the sticky bit is set.
@c =  $B8m?"(B?        owner
$BLa$jCM$N:GBgCM$O(B4095$B!J(B8$B?J?t(B7777$B!K$G$"$j!"$3$l$O!"(B
$B$@$l$b$,FI$_!?=q$-!?<B9T$G$-!"(B
$B=jM-<T$H%0%k!<%W$NN><T$K%S%C%H(B@sc{suid}$B$,@_Dj$7$F$"$j!"(B
$B%9%F%#%C%-!<%S%C%H$b@_Dj$5$l$F$$$k$3$H$r0UL#$9$k!#(B

@example
@group
(file-modes "~/junk/diffs")
@c      @result{} 492               ; @r{Decimal integer.}
     @result{} 492               ; @r{10$B?J@0?t(B}
@end group
@group
(format "%o" 492)
@c      @result{} "754"             ; @r{Convert to octal.}
     @result{} "754"             ; @r{8$B?J?t$KJQ49(B}
@end group

@group
(set-file-modes "~/junk/diffs" 438)
     @result{} nil
@end group

@group
(format "%o" 438)
@c      @result{} "666"             ; @r{Convert to octal.}
     @result{} "666"             ; @r{8$B?J?t$KJQ49(B}
@end group

@group
% ls -l diffs
  -rw-rw-rw-  1 lewis 0 3063 Oct 30 16:00 diffs
@end group
@end example
@end defun

@defun file-nlinks filename
@c This functions returns the number of names (i.e., hard links) that
@c file @var{filename} has.  If the file does not exist, then this function
@c returns @code{nil}.  Note that symbolic links have no effect on this
@c function, because they are not considered to be names of the files they
@c link to.
$B$3$N4X?t$O!"%U%!%$%k(B@var{filename}$B$N(B
$BL>A0!J$D$^$j%O!<%I%j%s%/!K$N8D?t$rJV$9!#(B
$B%U%!%$%k$,B8:_$7$J$1$l$P!"$3$N4X?t$O(B@code{nil}$B$rJV$9!#(B
$B%7%s%\%j%C%/%j%s%/$O$=$l$,;X$9%U%!%$%k$NL>A0$H$O$_$J$5$J$$$N$G!"(B
$B%7%s%\%j%C%/%j%s%/$O$3$N4X?t$K$O8z2L$r;}$?$J$$!#(B

@example
@group
% ls -l foo*
-rw-rw-rw-  2 rms       4 Aug 19 01:27 foo
-rw-rw-rw-  2 rms       4 Aug 19 01:27 foo1
@end group

@group
(file-nlinks "foo")
     @result{} 2
@end group
@group
(file-nlinks "doesnt-exist")
     @result{} nil
@end group
@end example
@end defun

@defun file-attributes filename
@c This function returns a list of attributes of file @var{filename}.  If
@c the specified file cannot be opened, it returns @code{nil}.
$B$3$N4X?t$O%U%!%$%k(B@var{filename}$B$NB0@-$N%j%9%H$rJV$9!#(B
$B%*!<%W%s$G$-$J$$%U%!%$%k$r;XDj$9$k$H(B@code{nil}$B$rJV$9!#(B

@c The elements of the list, in order, are:
$B%j%9%H$NMWAG$O=g$K$D$.$N$H$*$j$G$"$k!#(B

@enumerate 0
@item
@c @code{t} for a directory, a string for a symbolic link (the name
@c linked to), or @code{nil} for a text file.
$B%G%#%l%/%H%j$O(B@code{t}$B!"(B
$B%7%s%\%j%C%/%j%s%/$O!J$=$l$,;X$9L>A0$N!KJ8;zNs!"(B
$B%F%-%9%H%U%!%$%k$O(B@code{nil}$B$G$"$k!#(B

@c Wordy so as to prevent an overfull hbox.  --rjc 15mar92
@item
@c The number of names the file has.  Alternate names, also known as hard
@c links, can be created by using the @code{add-name-to-file} function
@c (@pxref{Changing Files}).
$B%U%!%$%k$NL>A0$N8D?t!#(B
$BJL$NL>A0!"$D$^$j!"(B
$B%O!<%I%j%s%/$O4X?t(B@code{add-name-to-file}$B!J(B@pxref{Changing Files}$B!K(B
$B$r;H$C$F:n@.$9$k!#(B

@item
@c The file's @sc{uid}.
$B%U%!%$%k$N(B@sc{uid}$B!J=jM-<THV9f!K!#(B

@item
@c The file's @sc{gid}.
$B%U%!%$%k$N(B@sc{gid}$B!J%0%k!<%WHV9f!K!#(B

@item
@c The time of last access, as a list of two integers.
@c The first integer has the high-order 16 bits of time,
@c the second has the low 16 bits.  (This is similar to the
@c value of @code{current-time}; see @ref{Time of Day}.)
2$B$D$N@0?t$+$i@.$k%j%9%H$H$7$F$N:G=*;2>H;~9o!#(B
$B:G=i$N@0?t$O;~9o$N>e0L(B16$B%S%C%H$G$"$j!"(B2$BHVL\$O2<0L(B16$B%S%C%H!#(B
$B!J$3$l$O(B@code{current-time}$B$NCM$HF1MM!#(B
@ref{Time of Day}$B$r;2>H!#!K(B

@item
@c The time of last modification as a list of two integers (as above).
2$B$D$N@0?t$+$i@.$k%j%9%H$H$7$F$N:G=*99?7;~9o!J>e5-$HF1MM!K!#(B

@item
@c The time of last status change as a list of two integers (as above).
2$B$D$N@0?t$+$i@.$k%j%9%H$H$7$F$N:G=*>uBV99?7;~9o!J>e5-$HF1MM!K!#(B

@item
@c The size of the file in bytes.
$B%P%$%HC10L$G$N%U%!%$%k$N%5%$%:!#(B

@item
@c The file's modes, as a string of ten letters or dashes,
@c as in @samp{ls -l}.
@samp{ls -l}$B$HF1MM$N%U%!%$%k$N%b!<%I$rI=$9(B10$BJ8;z$NJ8;zNs!#(B

@item
@c @code{t} if the file's @sc{gid} would change if file were
@c deleted and recreated; @code{nil} otherwise.
$B$b$7%U%!%$%k$r:o=|$7$F:FEY:n@.$7$?>l9g$K(B
$B%U%!%$%k$N(B@sc{gid}$B!J%0%k!<%WHV9f!K$,JQ$o$k>l9g$K$O(B@code{t}$B!#(B
$B$5$b$J$1$l$P(B@code{nil}$B!#(B

@item
@c The file's inode number.  If possible, this is an integer.  If the inode
@c number is too large to be represented as an integer in Emacs Lisp, then
@c the value has the form @code{(@var{high} . @var{low})}, where @var{low}
@c holds the low 16 bits.
$B%U%!%$%k$N(Bi$B%N!<%IHV9f!#(B
$B2DG=$J$i$P$3$l$O@0?t$G$"$k!#(B
i$B%N!<%IHV9f$,(BEmacs Lisp$B$N@0?t$H$7$FI=8=$G$-$J$$$[$IBg$-$J>l9g!"(B
$BCM$O(B@code{(@var{high} . @var{low})}$B$N7A$G$"$k!#(B
$B$?$@$7!"(B@var{low}$B$O2<0L(B16$B%S%C%H$G$"$k!#(B

@item
@c The file system number of the file system that the file is in.  This
@c element and the file's inode number together give enough information to
@c distinguish any two files on the system---no two files can have the same
@c values for both of these numbers.
$B%U%!%$%k$,CV$$$F$"$k%U%!%$%k%7%9%F%`$N%U%!%$%k%7%9%F%`HV9f!#(B
$B$3$NMWAG$H%U%!%$%k$N(Bi$B%N!<%IHV9f$K$h$j!"(B
$B%7%9%F%`>e$NG$0U$N(B2$B$D$N%U%!%$%k$r6hJL$9$k$?$a$K==J,$J>pJs$rM?$($k!#(B
$B$D$^$j!"(B2$B$D$N%U%!%$%k$,F1$8CM$N$3$l$i$NHV9f$r;}$D$3$H$O$J$$!#(B
@end enumerate

@c For example, here are the file attributes for @file{files.texi}:
$B$?$H$($P!"(B@file{files.texi}$B$N%U%!%$%kB0@-$O$D$.$N$h$&$G$"$k!#(B

@example
@group
(file-attributes "files.texi")
     @result{}  (nil 1 2235 75 
          (8489 20284) 
          (8489 20284) 
          (8489 20285)
          14906 "-rw-rw-rw-" 
          nil 129500 -32252)
@end group
@end example

@noindent
@c and here is how the result is interpreted:
$B$3$N0UL#$O$D$.$N$H$*$j$G$"$k!#(B

@table @code
@item nil
@c is neither a directory nor a symbolic link.
$B%G%#%l%/%H%j$G$b%7%s%\%j%C%/%j%s%/$G$b$J$$!#(B

@item 1
@c has only one name (the name @file{files.texi} in the current default
@c directory).
$BM#0l$NL>A0!J%+%l%s%H%G%#%l%/%H%j$G(B@file{files.texi}$B!K$r;}$D!#(B

@item 2235
@c is owned by the user with @sc{uid} 2235.
@sc{uid}$B!J%f!<%6!<HV9f!K(B2235$B$N%f!<%6!<$,=jM-$7$F$$$k!#(B

@item 75
@c is in the group with @sc{gid} 75.
@sc{gid}$B!J%0%k!<%WHV9f!K(B75$B$N%0%k!<%W$KB0$9$k!#(B

@item (8489 20284)
@c was last accessed on Aug 19 00:09.
$B:G8e$K;2>H$5$l$?$N$O(B8$B7n(B19$BF|(B00$B;~(B09$BJ,$G$"$k!#(B

@item (8489 20284)
@c was last modified on Aug 19 00:09.
$B:G8e$K99?7$5$l$?$N$O(B8$B7n(B19$BF|(B00$B;~(B09$BJ,$G$"$k!#(B

@item (8489 20285)
@c last had its inode changed on Aug 19 00:09.
$B:G8e$K$3$N(Bi$B%N!<%I$rJQ99$7$?$N$O(B8$B7n(B19$BF|(B00$B;~(B09$BJ,$G$"$k!#(B

@item 14906
@c is 14906 characters long.
$BD9$5$O(B14906$B%P%$%H$G$"$k!#(B

@item "-rw-rw-rw-"
@c has a mode of read and write access for the owner, group, and world.
$B%b!<%I$O!"=jM-<T!?%0%k!<%W!?$=$NB>$OFI$_=q$-$G$-$k!#(B

@item nil
@c would retain the same @sc{gid} if it were recreated.
$B:FEY:n@.$7$F$b(B@sc{gid}$B!J%0%k!<%WHV9f!K$OJ]B8$5$l$k!#(B

@item 129500
@c has an inode number of 129500.
i$B%N!<%IHV9f$O(B129500$B!#(B
@item -32252
@c is on file system number -32252.
$B%U%!%$%k%7%9%F%`HV9f$O(B-32252$B!#(B
@end table
@end defun

@node Changing Files
@c @section Changing File Names and Attributes
@section $B%U%!%$%k$NL>A0$HB0@-$NJQ99(B
@c @cindex renaming files
@c @cindex copying files
@c @cindex deleting files
@c @cindex linking files
@c @cindex setting modes of files
@cindex $B%U%!%$%k$N2~L>(B
@cindex $B%U%!%$%k$N%3%T!<(B
@cindex $B%U%!%$%k$N:o=|(B
@cindex $B%U%!%$%k$N%j%s%/(B
@cindex $B%U%!%$%k$N%b!<%I$N@_Dj(B

@c   The functions in this section rename, copy, delete, link, and set the
@c modes of files.
$BK\@a$N4X?t$O!"%U%!%$%k$r2~L>!?%3%T!<!?:o=|!?%j%s%/$7$?$j!"(B
$B%U%!%$%k$N%b!<%I$r@_Dj$9$k$?$a$N$b$N$G$9!#(B

@c   In the functions that have an argument @var{newname}, if a file by the
@c name of @var{newname} already exists, the actions taken depend on the
@c value of the argument @var{ok-if-already-exists}:
$B0z?t(B@var{newname}$B$r$H$k4X?t$G$O!"(B
@var{newname}$B$G;XDj$7$?%U%!%$%k$,4{B8$N>l9g!"(B
$B4X?t$NF0:n$O0z?t(B@var{ok-if-already-exists}$B$NCM$K0MB8$7$^$9!#(B

@itemize @bullet
@item
@c Signal a @code{file-already-exists} error if
@c @var{ok-if-already-exists} is @code{nil}.
@var{ok-if-already-exists}$B$,(B@code{nil}$B$G$"$k$H!"(B
$B%(%i!<(B@code{file-already-exists}$B$rDLCN$9$k!#(B

@item
@c Request confirmation if @var{ok-if-already-exists} is a number.
@var{ok-if-already-exists}$B$,?t$G$"$k$H!"3NG'$rI,MW$H$9$k!#(B

@item
@c Replace the old file without confirmation if @var{ok-if-already-exists}
@c is any other value.
@var{ok-if-already-exists}$B$,$=$l0J30$NCM$G$"$k$H!"(B
$B3NG'$;$:$K8E$$%U%!%$%k$rCV$-49$($k!#(B
@end itemize

@defun add-name-to-file oldname newname &optional ok-if-already-exists
@c @cindex file with multiple names
@c @cindex file hard link
@cindex $BJ#?t$NL>A0$N%U%!%$%k(B
@cindex $B%U%!%$%k$N%O!<%I%j%s%/(B
@c This function gives the file named @var{oldname} the additional name
@c @var{newname}.  This means that @var{newname} becomes a new ``hard
@c link'' to @var{oldname}.
$B$3$N4X?t$O!"(B@var{oldname}$B$G;XDj$7$?%U%!%$%k$K(B
$BDI2C$NL>A0(B@var{newname}$B$rM?$($k!#(B
$B$D$^$j!"(B@var{newname}$B$O(B@var{oldname}$B$X$N?7$?$J!X%O!<%I%j%s%/!Y$K$J$k!#(B

@c In the first part of the following example, we list two files,
@c @file{foo} and @file{foo3}.
$B$D$.$NNc$G$O!"(B2$B$D$N%U%!%$%k(B@file{foo}$B$H(B@file{foo3}$B$,$"$k!#(B

@example
@group
% ls -li fo*
81908 -rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
@end group
@end example

@c Now we create a hard link, by calling @code{add-name-to-file}, then list
@c the files again.  This shows two names for one file, @file{foo} and
@c @file{foo2}.
@code{add-name-to-file}$B$r8F$s$G%O!<%I%j%s%/$r:n@.$7!"(B
$B%U%!%$%k0lMw$rI=<($7D>$9!#(B
1$B$D$N%U%!%$%k$K(B2$B$D$NL>A0(B@file{foo}$B$H(B@file{foo2}$B$,$"$k$3$H$,$o$+$k!#(B

@example
@group
(add-name-to-file "foo" "foo2")
     @result{} nil
@end group

@group
% ls -li fo*
81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
@end group
@end example

@c Finally, we evaluate the following:
$B:G8e$K$D$.$N<0$rI>2A$7(B

@example
(add-name-to-file "foo" "foo3" t)
@end example

@noindent
@c and list the files again.  Now there are three names
@c for one file: @file{foo}, @file{foo2}, and @file{foo3}.  The old
@c contents of @file{foo3} are lost.
$B%U%!%$%k0lMw$rI=<($7D>$9!#(B
$B:#EY$O!"(B1$B$D$N%U%!%$%k$K(B3$B$D$NL>A0(B@file{foo}$B!"(B@file{foo2}$B!"(B@file{foo3}$B$,$"$k!#(B
$B8E$$(B@file{foo3}$B$NFbMF$O<:$o$l$F$$$k!#(B

@example
@group
(add-name-to-file "foo1" "foo3")
     @result{} nil
@end group

@group
% ls -li fo*
81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3
@end group
@end example

@c This function is meaningless on operating systems where multiple names
@c for one file are not allowed.
1$B$D$N%U%!%$%k$KJ#?t$NL>A0$r5v$5$J$$%*%Z%l!<%F%#%s%0%7%9%F%`$G$O!"(B
$B$3$N4X?t$O0UL#$,$J$$!#(B

@c See also @code{file-nlinks} in @ref{File Attributes}.
@ref{File Attributes}$B$N(B@code{file-nlinks}$B$b;2>H!#(B
@end defun

@c @deffn Command rename-file filename newname &optional ok-if-already-exists
@deffn $B%3%^%s%I(B rename-file filename newname &optional ok-if-already-exists
@c This command renames the file @var{filename} as @var{newname}.
$B$3$N%3%^%s%I$O!"%U%!%$%k(B@var{filename}$B$r(B@var{newname}$B$H2~L>$9$k!#(B

@c If @var{filename} has additional names aside from @var{filename}, it
@c continues to have those names.  In fact, adding the name @var{newname}
@c with @code{add-name-to-file} and then deleting @var{filename} has the
@c same effect as renaming, aside from momentary intermediate states.
@var{filename}$B$K(B@var{filename}$B0J30$NL>A0$,$"$l$P!"(B
$B$=$l$i$NL>A0$OB8:_$7B3$1$k!#(B
$B<B:]!"(B@code{add-name-to-file}$B$GL>A0(B@var{newname}$B$rDI2C$7$F$+$i(B
@var{filename}$B$r:o=|$9$k$H!"0l;~E*$JCf4V>uBV$,$"$k$3$H$r=|$1$P!"(B
$B2~L>$HF1$88z2L$,$"$k!#(B

@c In an interactive call, this function prompts for @var{filename} and
@c @var{newname} in the minibuffer; also, it requests confirmation if
@c @var{newname} already exists.
$BBPOCE*$K8F$S=P$5$l$k$H!"$3$N4X?t$O(B
$B%_%K%P%C%U%!$G(B@var{filename}$B$H(B@var{newname}$B$rJ9$/!#(B
$B$^$?!"(B@var{newname}$B$,4{B8$G$"$k$H3NG'$r5a$a$k!#(B
@end deffn

@c @deffn Command copy-file oldname newname &optional ok-if-exists time
@deffn $B%3%^%s%I(B copy-file oldname newname &optional ok-if-exists time
@c This command copies the file @var{oldname} to @var{newname}.  An
@c error is signaled if @var{oldname} does not exist.
$B$3$N%3%^%s%I$O%U%!%$%k(B@var{oldname}$B$r(B@var{newname}$B$X%3%T!<$9$k!#(B
@var{oldname}$B$,B8:_$7$J$$$H%(%i!<$rDLCN$9$k!#(B

@c If @var{time} is non-@code{nil}, then this function gives the new file
@c the same last-modified time that the old one has.  (This works on only
@c some operating systems.)  If setting the time gets an error,
@c @code{copy-file} signals a @code{file-date-error} error.
@var{time}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B$3$N4X?t$O?7$?$J%U%!%$%k$K8E$$%U%!%$%k$HF1$8:G=*99?7;~9o$rM?$($k!#(B
$B!J$3$l$OFCDj$N%*%Z%l!<%F%#%s%0%7%9%F%`$G$N$_F0:n$9$k!#!K(B
$B;~9o@_Dj$G%(%i!<$,$"$k$H!"(B@code{copy-file}$B$O(B
$B%(%i!<(B@code{file-date-error}$B$rDLCN$9$k!#(B

@c = $B8m?"(B filename $B"*(B oldname
@c In an interactive call, this function prompts for @var{filename} and
@c @var{newname} in the minibuffer; also, it requests confirmation if
@c @var{newname} already exists.
$BBPOCE*$K8F$S=P$5$l$k$H!"$3$N4X?t$O(B
$B%_%K%P%C%U%!$G(B@var{oldname}$B$H(B@var{newname}$B$rJ9$/!#(B
$B$^$?!"(B@var{newname}$B$,4{B8$G$"$k$H3NG'$r5a$a$k!#(B
@end deffn

@c @deffn Command delete-file filename
@deffn $B%3%^%s%I(B delete-file filename
@pindex rm
@c This command deletes the file @var{filename}, like the shell command
@c @samp{rm @var{filename}}.  If the file has multiple names, it continues
@c to exist under the other names.
$B$3$N%3%^%s%I$O!"%7%'%k%3%^%s%I(B@samp{rm @var{filename}}$B$HF1MM$K(B
$B%U%!%$%k(B@var{filename}$B$r:o=|$9$k!#(B
$B%U%!%$%k$KJ#?t$NL>A0$,$"$k$H!"B>$NL>A0$G$OB8:_$7B3$1$k!#(B

@c A suitable kind of @code{file-error} error is signaled if the file
@c does not exist, or is not deletable.  (On Unix, a file is deletable if
@c its directory is writable.)
$B%U%!%$%k$,B8:_$7$J$+$C$?$j:o=|$G$-$J$$$H!"(B
$B%(%i!<(B@code{file-error}$B$NE,@Z$J<oN`$,DLCN$5$l$k!#(B
$B!J(BUNIX$B$G$O!"%U%!%$%k$r<}$a$?%G%#%l%/%H%j$K=q$1$k$H(B
$BEv3:%U%!%$%k$O:o=|2DG=$G$"$k!#!K(B

@c See also @code{delete-directory} in @ref{Create/Delete Dirs}.
@ref{Create/Delete Dirs}$B$N(B@code{delete-directory}$B$b;2>H!#(B
@end deffn

@c @deffn Command make-symbolic-link filename newname  &optional ok-if-exists
@deffn $B%3%^%s%I(B make-symbolic-link filename newname  &optional ok-if-exists
@pindex ln
@kindex file-already-exists
@c This command makes a symbolic link to @var{filename}, named
@c @var{newname}.  This is like the shell command @samp{ln -s
@c @var{filename} @var{newname}}.
$B$3$N%3%^%s%I$O!"(B@var{filename}$B$KBP$9$k%7%s%\%j%C%/%j%s%/(B@var{newname}$B$r(B
$B:n@.$9$k!#(B
$B$3$l$O%7%'%k%3%^%s%I(B@samp{ln -s @var{filename} @var{newname}}$B$HF1$8$G$"$k!#(B

@c In an interactive call, this function prompts for @var{filename} and
@c @var{newname} in the minibuffer; also, it requests confirmation if
@c @var{newname} already exists.
$BBPOCE*$K8F$S=P$5$l$k$H!"$3$N4X?t$O(B
$B%_%K%P%C%U%!$G(B@var{filename}$B$H(B@var{newname}$B$rJ9$/!#(B
$B$^$?!"(B@var{newname}$B$,4{B8$G$"$k$H3NG'$r5a$a$k!#(B
@end deffn

@c @defun define-logical-name varname string
@c = $B8m?"!)(B                      name
@defun define-logical-name name string
@c This function defines the logical name @var{name} to have the value
@c @var{string}.  It is available only on VMS.
$B$3$N4X?t$OO@M}L>(B@var{name}$B$KCM(B@var{string}$B$rDj5A$9$k!#(B
VMS$B$G$N$_;H$($k!#(B
@end defun

@defun set-file-modes filename mode
@c This function sets mode bits of @var{filename} to @var{mode} (which must
@c be an integer).  Only the low 12 bits of @var{mode} are used.
$B$3$N4X?t$O(B@var{filename}$B$N%b!<%I%S%C%H$r(B
@var{mode}$B!J@0?t$G$"$k$3$H!K$H@_Dj$9$k!#(B
@var{mode}$B$N2<0L(B12$B%S%C%H$N$_$r;H$&!#(B
@end defun

@c Emacs 19 feature
@defun set-default-file-modes mode
@c This function sets the default file protection for new files created by
@c Emacs and its subprocesses.  Every file created with Emacs initially has
@c this protection.  On Unix, the default protection is the bitwise
@c complement of the ``umask'' value.
$B$3$N4X?t$O!"(BEmacs$B$d$=$N%5%V%W%m%;%9$,:n@.$9$k?75,%U%!%$%k$N(B
$B%G%U%)%k%H$N%U%!%$%k%b!<%I$r@_Dj$9$k!#(B
Emacs$B$,:n@.$9$k3F%U%!%$%k$O:G=i$3$N%b!<%I$K$J$k!#(B
UNIX$B$G$O!"%G%U%)%k%H$N%b!<%I$O!X(Bumask$B!Y$NCM$N(B1$B$NJd?t$G$"$k!#(B

@c The argument @var{mode} must be an integer.  On most systems, only the
@c low 9 bits of @var{mode} are meaningful.
$B0z?t(B@var{mode}$B$O@0?t$G$"$k$3$H!#(B
$B$[$H$s$I$N%7%9%F%`$G$O!"(B@var{mode}$B$N2<0L(B9$B%S%C%H$N$_$,0UL#$r;}$D!#(B

@c Saving a modified version of an existing file does not count as creating
@c the file; it does not change the file's mode, and does not use the
@c default file protection.
$B4{B8%U%!%$%k$NJQ99$rJ]B8$9$k$3$H$O%U%!%$%k$N:n@.$H$O$_$J$5$J$$$?$a!"(B
$B%U%!%$%k$N%b!<%I$OJQ$o$i$:!"%G%U%)%k%H$N%U%!%$%k%b!<%I$r;H$o$J$$!#(B
@end defun

@defun default-file-modes
@c This function returns the current default protection value.
$B$3$N4X?t$O!"8=:_$N%G%U%)%k%H$N%U%!%$%k%b!<%I$NCM$rJV$9!#(B
@end defun

@c @cindex MS-DOS and file modes
@c @cindex file modes and MS-DOS
@cindex MS-DOS$B$H%U%!%$%k%b!<%I(B
@cindex $B%U%!%$%k%b!<%I$H(BMS-DOS
@c   On MS-DOS, there is no such thing as an ``executable'' file mode bit.
@c So Emacs considers a file executable if its name ends in @samp{.com},
@c @samp{.bat} or @samp{.exe}.  This is reflected in the values returned
@c by @code{file-modes} and @code{file-attributes}.
MS-DOS$B$G$O!"!X<B9T2DG=!Y%U%!%$%k%b!<%I%S%C%H$N$h$&$J$b$N$O$"$j$^$;$s!#(B
$B$=$N$?$a(BEmacs$B$O!"(B@samp{.com}$B!"(B@samp{.bat}$B!"(B@samp{.exe}$B$N$$$:$l$+$G(B
$B=*$kL>A0$N%U%!%$%k$r<B9T2DG=$G$"$k$H$_$J$7$^$9!#(B
$B$3$l$O!"(B@code{file-modes}$B$d(B@code{file-attributes}$B$,JV$9CM$KH?1G$5$l$^$9!#(B

@node File Names
@c @section File Names
@section $B%U%!%$%kL>(B
@c @cindex file names
@cindex $B%U%!%$%kL>(B

@c   Files are generally referred to by their names, in Emacs as elsewhere.
@c File names in Emacs are represented as strings.  The functions that
@c operate on a file all expect a file name argument.
$BB>$N>lLL$HF1MM$K(BEmacs$B$G$O!"0lHL$K%U%!%$%k$O$=$NL>A0$G;2>H$7$^$9!#(B
Emacs$B$G$O%U%!%$%kL>$OJ8;zNs$GI=$7$^$9!#(B
$B%U%!%$%k$rA`:n$9$k4X?t$O$9$Y$F%U%!%$%kL>0z?t$r2>Dj$7$^$9!#(B

@c   In addition to operating on files themselves, Emacs Lisp programs
@c often need to operate on file names; i.e., to take them apart and to use
@c part of a name to construct related file names.  This section describes
@c how to manipulate file names.
$B%U%!%$%k<+BN$NA`:n$K2C$($F!"(BEmacs Lisp$B%W%m%0%i%`$O(B
$B%U%!%$%k$NL>A0$=$N$b$N$rA`:n$9$kI,MW$,$"$j$^$9!#(B
$B$D$^$j!"%U%!%$%kL>$rJ,2r$7$?$j!"4XO"$9$k%U%!%$%kL>$r:n@.$9$k$?$a$K(B
$B$=$N0lIt$r;H$$$^$9!#(B
$BK\@a$G$O%U%!%$%kL>$rA`:n$9$kJ}K!$r@bL@$7$^$9!#(B

@c   The functions in this section do not actually access files, so they
@c can operate on file names that do not refer to an existing file or
@c directory.
$BK\@a$N4X?t$O<B:]$K$O%U%!%$%k$r;2>H$7$^$;$s$+$i!"(B
$B4{B8$N%U%!%$%k$d%G%#%l%/%H%j$rI=$5$J$$%U%!%$%kL>$rA`:n$G$-$^$9!#(B

@c   On VMS, all these functions understand both VMS file-name syntax and
@c Unix syntax.  This is so that all the standard Lisp libraries can
@c specify file names in Unix syntax and work properly on VMS without
@c change.  On MS-DOS and MS-Windows, these functions understand MS-DOS or
@c MS-Windows file-name syntax as well as Unix syntax.
VMS$B$G$O!"$3$l$i$N4X?t$O$9$Y$F!"(BVMS$B$N%U%!%$%kL>9=J8$H(B
UNIX$B$N9=J8$NN>J}$rM}2r$7$^$9!#(B
$B$D$^$j!"I8=`(BLisp$B%i%$%V%i%j$O(BUNIX$B9=J8$G%U%!%$%kL>$r;XDj$G$-!"(B
$BJQ99$;$:$K(BVMS$B>e$G@5$7$/F0:n$7$^$9!#(B
MS-DOS$B$d(BMS-Windows$B$G$O!"$3$l$i$N4X?t$O!"(B
UNIX$B9=J8$K2C$($F(BMS-DOS$B$d(BMS-Windows$B$N%U%!%$%kL>9=J8$rM}2r$7$^$9!#(B

@menu
* File Name Components::  The directory part of a file name, and the rest.
* Directory Names::       A directory's name as a directory
                            is different from its name as a file.
* Relative File Names::   Some file names are relative to a current directory.
* File Name Expansion::   Converting relative file names to absolute ones.
* Unique File Names::     Generating names for temporary files.
* File Name Completion::  Finding the completions for a given file name.
* Standard File Names::   If your package uses a fixed file name,
                            how to handle various operating systems simply.
@end menu

@node File Name Components
@c @subsection File Name Components
@subsection $B%U%!%$%kL>$N9=@.MWAG(B
@c @cindex directory part (of file name)
@c @cindex nondirectory part (of file name)
@c @cindex version number (in file name)
@cindex $B%G%#%l%/%H%jItJ,!J%U%!%$%kL>!K(B
@cindex $BHs%G%#%l%/%H%jItJ,!J%U%!%$%kL>!K(B
@cindex $BHGHV9f!J%U%!%$%kL>!K(B

@c   The operating system groups files into directories.  To specify a
@c file, you must specify the directory and the file's name within that
@c directory.  Therefore, Emacs considers a file name as having two main
@c parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
@c (or @dfn{file name within the directory}).  Either part may be empty.
@c Concatenating these two parts reproduces the original file name.
$B%*%Z%l!<%F%#%s%0%7%9%F%`$O!"0lO"$N%U%!%$%k$r%G%#%l%/%H%j$K$^$H$a$^$9!#(B
$B%U%!%$%k$r;XDj$9$k$K$O!"%G%#%l%/%H%j$HEv3:%G%#%l%/%H%jFb$N%U%!%$%k$NL>A0$r(B
$B;XDj$9$kI,MW$,$"$j$^$9!#(B
$B$=$N$?$a(BEmacs$B$O!"%U%!%$%kL>$K$O(B2$B$D$NItJ,!"(B
@dfn{$B%G%#%l%/%H%jL>(B}$B!J(Bdirectory name$B!KItJ,$H(B
@dfn{$BHs%G%#%l%/%H%jL>(B}$B!J(Bnondirectory name$B!KItJ,(B
$B!J$D$^$j(B@dfn{$B%G%#%l%/%H%jFb$N%U%!%$%kL>(B}$B!K$,$"$k$H$_$J$7$^$9!#(B
$B$I$A$i$+$NItJ,$O6u$G$b$+$^$$$^$;$s!#(B
$B$3$l$i$N(B2$B$D$NItJ,$rO"7k$9$k$H$b$H$N%U%!%$%kL>$K$J$j$^$9!#(B

@c   On Unix, the directory part is everything up to and including the last
@c slash; the nondirectory part is the rest.  The rules in VMS syntax are
@c complicated.
UNIX$B$G$O!"%G%#%l%/%H%jItJ,$O:G8e$N%9%i%C%7%e$^$G$r4^$s$@ItJ,$G$"$j!"(B
$BHs%G%#%l%/%H%jItJ,$O;D$j$NItJ,$G$9!#(B
VMS$B$N9=J85,B'$OJ#;($G$9!#(B

@c   For some purposes, the nondirectory part is further subdivided into
@c the name proper and the @dfn{version number}.  On Unix, only backup
@c files have version numbers in their names.  On VMS, every file has a
@c version number, but most of the time the file name actually used in
@c Emacs omits the version number, so that version numbers in Emacs are
@c found mostly in directory lists.
$B$"$k<o$NL\E*$N$?$a$K!"Hs%G%#%l%/%H%jItJ,$r$5$i$K(B
$BL>A0$@$1$NItJ,$H(B@dfn{$BHGHV9f(B}$B!J(Bversion number$B!K$KJ,$1$^$9!#(B
UNIX$B$G$O!"%P%C%/%"%C%W%U%!%$%k$@$1$K$=$l$i$NL>A0$KHGHV9f$,$"$j$^$9!#(B
VMS$B$G$O3F%U%!%$%k$KHGHV9f$,$"$j$^$9$,!"(B
$B$[$H$s$I$N>l9g!"(BEmacs$B$G<B:]$K;H$&%U%!%$%kL>$G$OHGHV9f$r>JN,$7$^$9!#(B
$B$=$N$?$a!"(BEmacs$B$GHGHV9f$,8+$($k$N$OB?$/$N>l9g%G%#%l%/%H%j0lMw$G$9!#(B

@defun file-name-directory filename
@c This function returns the directory part of @var{filename} (or
@c @code{nil} if @var{filename} does not include a directory part).  On
@c Unix, the function returns a string ending in a slash.  On VMS, it
@c returns a string ending in one of the three characters @samp{:},
@c @samp{]}, or @samp{>}.
$B$3$N4X?t$O(B@var{filename}$B$N%G%#%l%/%H%jItJ,(B
$B!J%G%#%l%/%H%jItJ,$,$J$1$l$P(B@code{nil}$B!K$rJV$9!#(B
UNIX$B$G$O!"$3$N4X?t$O%9%i%C%7%e$G=*$kJ8;zNs$rJV$9!#(B
VMS$B$G$O!"(B@samp{:}$B!"(B@samp{]}$B!"(B@samp{>}$B$N$$$:$l$+$G=*$kJ8;zNs$rJV$9!#(B

@example
@group
@c (file-name-directory "lewis/foo")  ; @r{Unix example}
(file-name-directory "lewis/foo")  ; @r{UNIX$B$NNc(B}
     @result{} "lewis/"
@end group
@group
@c (file-name-directory "foo")        ; @r{Unix example}
(file-name-directory "foo")        ; @r{UNIX$B$NNc(B}
     @result{} nil
@end group
@group
@c (file-name-directory "[X]FOO.TMP") ; @r{VMS example}
(file-name-directory "[X]FOO.TMP") ; @r{VMS$B$NNc(B}
     @result{} "[X]"
@end group
@end example
@end defun

@defun file-name-nondirectory filename
@c This function returns the nondirectory part of @var{filename}.
$B$3$N4X?t$O(B@var{filename}$B$NHs%G%#%l%/%H%jItJ,$rJV$9!#(B

@example
@group
(file-name-nondirectory "lewis/foo")
     @result{} "foo"
@end group
@group
(file-name-nondirectory "foo")
     @result{} "foo"
@end group
@group
@c ;; @r{The following example is accurate only on VMS.}
;; @r{$B$D$.$NNc$O(BVMS$B$G$N$_@53N$G$"$k(B}
(file-name-nondirectory "[X]FOO.TMP")
     @result{} "FOO.TMP"
@end group
@end example
@end defun

@defun file-name-sans-versions filename
@c This function returns @var{filename} with any file version numbers,
@c backup version numbers, or trailing tildes deleted.
$B$3$N4X?t$O!"(B@var{filename}$B$+$iHGHV9f!"%P%C%/%"%C%WHGHV9f!"(B
$BKvHx$N%F%#%k%@$r$9$Y$F:o=|$7$?$b$N$rJV$9!#(B

@example
@group
(file-name-sans-versions "~rms/foo.~1~")
     @result{} "~rms/foo"
@end group
@group
(file-name-sans-versions "~rms/foo~")
     @result{} "~rms/foo"
@end group
@group
(file-name-sans-versions "~rms/foo")
     @result{} "~rms/foo"
@end group
@group
@c ;; @r{The following example applies to VMS only.}
;; @r{$B$D$.$NNc$O(BVMS$B$G$N$_@53N$G$"$k(B}
(file-name-sans-versions "foo;23")
     @result{} "foo"
@end group
@end example
@end defun

@defun file-name-sans-extension filename
@c This function returns @var{filename} minus its ``extension,'' if any.
@c The extension, in a file name, is the part that starts with the last
@c @samp{.} in the last name component.  For example,
$B$3$N4X?t$O!"(B@var{filename}$B$+$i$"$l$P!X3HD%;R!Y$r=|$$$?$b$N$rJV$9!#(B
$B%U%!%$%kL>$N3HD%;R$H$O!"(B
$BL>A0$N:G8e$NItJ,$K$"$k(B@samp{.}$B$G;O$^$kItJ,$G$"$k!#(B
$B$?$H$($P$D$.$N$H$*$j$G$"$k!#(B

@example
(file-name-sans-extension "foo.lose.c")
     @result{} "foo.lose"
(file-name-sans-extension "big.hack/foo")
     @result{} "big.hack/foo"
@end example
@end defun

@node Directory Names
@comment  node-name,  next,  previous,  up
@c @subsection Directory Names
@subsection $B%G%#%l%/%H%jL>(B
@c @cindex directory name
@c @cindex file name of directory
@cindex $B%G%#%l%/%H%jL>(B
@cindex $B%G%#%l%/%H%j$N%U%!%$%kL>(B

@c   A @dfn{directory name} is the name of a directory.  A directory is a
@c kind of file, and it has a file name, which is related to the directory
@c name but not identical to it.  (This is not quite the same as the usual
@c Unix terminology.)  These two different names for the same entity are
@c related by a syntactic transformation.  On Unix, this is simple: a
@c directory name ends in a slash, whereas the directory's name as a file
@c lacks that slash.  On VMS, the relationship is more complicated.
@dfn{$B%G%#%l%/%H%jL>(B}$B!J(Bdirectory name$B!K$H$O%G%#%l%/%H%j$NL>A0$G$9!#(B
$B%G%#%l%/%H%j$O%U%!%$%k$N0l<o$G$"$j!"%U%!%$%kL>$r;}$A$^$9$,!"(B
$B$=$l$O%G%#%l%/%H%jL>$K4XO"IU$1$i$l$^$9$,F10l$G$O$"$j$^$;$s!#(B
$B!J$3$l$O(BUNIX$B$NDL>o$NMQ8l$HF1$8$G$O$J$$!#!K(B
$BF1$8$b$N$KBP$9$k$3$l$i$N0[$J$k(B2$B$D$NL>A0$O!"9=J8$NJQ49$G4XO"IU$1$^$9!#(B
UNIX$B$G$O$3$l$O4JC1$G$"$j!"%G%#%l%/%H%jL>$O%9%i%C%7%e$G=*$j$^$9$,!"(B
$B%U%!%$%k$H$7$F$N%G%#%l%/%H%j$NL>A0$K$O%9%i%C%7%e$O$"$j$^$;$s!#(B
VMS$B$G$O!"4X78$O$h$jJ#;($G$9!#(B

@c   The difference between a directory name and its name as a file is
@c subtle but crucial.  When an Emacs variable or function argument is
@c described as being a directory name, a file name of a directory is not
@c acceptable.
$B%G%#%l%/%H%jL>$H$=$N%U%!%$%k$H$7$F$NL>A0$H$N0c$$$O$o$:$+$G$9$,=EBg$G$9!#(B
Emacs$B$NJQ?t$d4X?t0z?t$,%G%#%l%/%H%jL>$H5-=R$5$l$F$$$k$H$-$K$O!"(B
$B%G%#%l%/%H%j$N%U%!%$%k$H$7$F$NL>A0$O<u$1IU$1$^$;$s!#(B

@c   The following two functions convert between directory names and file
@c names.  They do nothing special with environment variable substitutions
@c such as @samp{$HOME}, and the constructs @samp{~}, and @samp{..}.
$B$D$.$N(B2$B$D$N4X?t$O%G%#%l%/%H%jL>$H%U%!%$%k$H$7$F$NL>A0$rAj8_$KJQ49$7$^$9!#(B
$B$3$l$i$O!"(B@samp{$HOME}$B$J$I$N4D6-JQ?tCV49$d(B
@samp{~}$B$d(B@samp{..}$B$J$I$N9=B$$K$O$J$K$bFCJL$J$3$H$O$7$^$;$s!#(B

@defun file-name-as-directory filename
@c This function returns a string representing @var{filename} in a form
@c that the operating system will interpret as the name of a directory.  In
@c Unix, this means appending a slash to the string (if it does not already
@c end in one).  On VMS, the function converts a string of the form
@c @file{[X]Y.DIR.1} to the form @file{[X.Y]}.
$B$3$N4X?t$O!"%*%Z%l!<%F%#%s%0%7%9%F%`$,(B
$B%G%#%l%/%H%jL>$H2r<a$9$kI=8=$GI=$7$?(B@var{filename}$B$NJ8;zNs$rJV$9!#(B
UNIX$B$G$O!"J8;zNs$K!J:G8e$K%9%i%C%7%e$,$J$1$l$P!K%9%i%C%7%e$r(B
$BIU2C$9$k$3$H$r0UL#$9$k!#(B
VMS$B$G$O!"(B@file{[X]Y.DIR.1}$B$N7A$NJ8;zNs$r(B@file{[X.Y]}$B$N7A$KJQ49$9$k!#(B

@example
@group
(file-name-as-directory "~rms/lewis")
     @result{} "~rms/lewis/"
@end group
@end example
@end defun

@defun directory-file-name dirname
@c This function returns a string representing @var{dirname} in a form that
@c the operating system will interpret as the name of a file.  On Unix,
@c this means removing the final slash from the string.  On VMS, the
@c function converts a string of the form @file{[X.Y]} to
@c @file{[X]Y.DIR.1}.
$B$3$N4X?t$O!"%*%Z%l!<%F%#%s%0%7%9%F%`$,(B
$B%U%!%$%k$NL>A0$H2r<a$9$kI=8=$GI=$7$?(B@var{dirname}$B$NJ8;zNs$rJV$9!#(B
UNIX$B$G$O!"J8;zNs$N:G8e$N%9%i%C%7%e$r<h$j=|$/$3$H$r0UL#$9$k!#(B
VMS$B$G$O!"(B@file{[X.Y]}$B$N7A$NJ8;zNs$r(B@file{[X]Y.DIR.1}$B$N7A$KJQ49$9$k!#(B

@example
@group
(directory-file-name "~lewis/")
     @result{} "~lewis"
@end group
@end example
@end defun

@c @cindex directory name abbreviation
@cindex $B%G%#%l%/%H%jL>$N>JN,7A(B
@cindex $B>JN,7A!"%G%#%l%/%H%jL>(B
@c   Directory name abbreviations are useful for directories that are
@c normally accessed through symbolic links.  Sometimes the users recognize
@c primarily the link's name as ``the name'' of the directory, and find it
@c annoying to see the directory's ``real'' name.  If you define the link
@c name as an abbreviation for the ``real'' name, Emacs shows users the
@c abbreviation instead.
$B%7%s%\%j%C%/%j%s%/$r2p$7$FDL>o;2>H$5$l$k%G%#%l%/%H%j$K$O(B
$B%G%#%l%/%H%jL>$N>JN,7A$,M-MQ$G$9!#(B
$B%f!<%6!<$O%j%s%/$NL>A0$r%G%#%l%/%H%j$N!XL>A0!Y$H$7$P$7$P$_$J$7!"(B
$B%G%#%l%/%H%j$N!XK\Ev$N!YL>A0$r8+$k$N$r$o$:$i$o$7$/;W$&$3$H$,$"$j$^$9!#(B
$B%j%s%/L>$r!XK\Ev$N!YL>A0$N>JN,7A$HDj5A$7$F$*$/$H!"(B
Emacs$B$O%f!<%6!<$K>JN,7A$rI=<($7$^$9!#(B

@defvar directory-abbrev-alist
@c The variable @code{directory-abbrev-alist} contains an alist of
@c abbreviations to use for file directories.  Each element has the form
@c @code{(@var{from} . @var{to})}, and says to replace @var{from} with
@c @var{to} when it appears in a directory name.  The @var{from} string is
@c actually a regular expression; it should always start with @samp{^}.
@c The function @code{abbreviate-file-name} performs these substitutions.
$BJQ?t(B@code{directory-abbrev-alist}$B$O!"(B
$B%G%#%l%/%H%j$K;H$&>JN,7A$NO"A[%j%9%H$rJ];}$9$k!#(B
$B3FMWAG$O(B@code{(@var{from} . @var{to})}$B$N7A$G$"$j!"(B
$B%G%#%l%/%H%jL>$K(B@var{from}$B$,8=$l$k$H$3$l$r(B@var{to}$B$KCV$-49$($k$3$H$r;X<($9$k!#(B
$BJ8;zNs(B@var{from}$B$O<B:]$K$O@55,I=8=$G$"$j!"$D$M$K(B@samp{^}$B$G;O$^$k$3$H!#(B
$B4X?t(B@code{abbreviate-file-name}$B$,$3$l$i$NCV49$r9T$&!#(B

@c You can set this variable in @file{site-init.el} to describe the
@c abbreviations appropriate for your site.
$B%U%!%$%k(B@file{site-init.el}$B$G$3$NJQ?t$K@_Dj$7!"(B
$BFI<T$N%5%$%H$KE,$7$?>JN,7A$r5-=R$G$-$k!#(B

@c Here's an example, from a system on which file system @file{/home/fsf}
@c and so on are normally accessed through symbolic links named @file{/fsf}
@c and so on.
$B%U%!%$%k%7%9%F%`(B@file{/home/fsf}$B$J$I$r%7%s%\%j%C%/L>(B@file{/fsf}$B$GDL>o;2>H$9$k(B
$B%7%9%F%`$NNc$r$D$.$K<($9!#(B

@example
(("^/home/fsf" . "/fsf")
 ("^/home/gp" . "/gp")
 ("^/home/gd" . "/gd"))
@end example
@end defvar

@c   To convert a directory name to its abbreviation, use this
@c function:
$B%G%#%l%/%H%jL>$r$=$N>JN,7A$KJQ49$9$k$K$O!"$D$.$N4X?t$r;H$$$^$9!#(B

@defun abbreviate-file-name dirname
@c This function applies abbreviations from @code{directory-abbrev-alist}
@c to its argument, and substitutes @samp{~} for the user's home
@c directory.
$B$3$N4X?t$O!"(B@code{directory-abbrev-alist}$B$N>JN,7A$r0z?t$KE,MQ$7!"(B
$B%f!<%6!<$N%[!<%`%G%#%l%/%H%j$r(B@samp{~}$B$KCV$-49$($k!#(B
@end defun

@node Relative File Names
@c @subsection Absolute and Relative File Names
@subsection $B%U%!%$%k$N@dBPL>$HAjBPL>(B
@c @cindex absolute file name
@c @cindex relative file name
@cindex $B@dBP%U%!%$%kL>(B
@cindex $BAjBP%U%!%$%kL>(B

@c   All the directories in the file system form a tree starting at the
@c root directory.  A file name can specify all the directory names
@c starting from the root of the tree; then it is called an @dfn{absolute}
@c file name.  Or it can specify the position of the file in the tree
@c relative to a default directory; then it is called a @dfn{relative}
@c file name.  On Unix, an absolute file name starts with a slash or a
@c tilde (@samp{~}), and a relative one does not.  The rules on VMS are
@c complicated.
$B%U%!%$%k%7%9%F%`Fb$N$9$Y$F$N%G%#%l%/%H%j$O!"(B
$B%k!<%H%G%#%l%/%H%j$+$i;O$^$kLZ$r7A:n$j$^$9!#(B
$B%U%!%$%kL>$G$O!"LZ$N%k!<%H$+$i;O$^$k$9$Y$F$N%G%#%l%/%H%jL>$r;XDj$G$-$F!"(B
$B$3$l$r(B@dfn{$B@dBP(B}$B!J(Babsolute$B!K%U%!%$%kL>$H8F$S$^$9!#(B
$B$"$k$$$O!"%G%U%)%k%H%G%#%l%/%H%j$r4p=`$K(B
$BLZ$NCf$G$N%U%!%$%k$N0LCV$r;XDj$9$k$3$H$b$G$-!"(B
$B$3$l$r(B@dfn{$BAjBP(B}$B!J(Brelative$B!K%U%!%$%kL>$H8F$S$^$9!#(B
UNIX$B$G$O!"@dBP%U%!%$%kL>$O%9%i%C%7%e$+%F%#%k%@!J(B@samp{~}$B!K$G;O$^$j!"(B
$BAjBP%U%!%$%kL>$O$=$l$i$G$O;O$^$j$^$;$s!#(B
VMS$B$G$N5,B'$OJ#;($G$9!#(B

@defun file-name-absolute-p filename
@c This function returns @code{t} if file @var{filename} is an absolute
@c file name, @code{nil} otherwise.  On VMS, this function understands both
@c Unix syntax and VMS syntax.
$B$3$N4X?t$O!"%U%!%$%k(B@var{filename}$B$,@dBP%U%!%$%kL>$G$"$l$P(B@code{t}$B$rJV$7!"(B
$B$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
VMS$B>e$G$O!"$3$N4X?t$O(BUNIX$B$N9=J8$H(BVMS$B$N9=J8$NN>J}$rM}2r$9$k!#(B

@example
@group
(file-name-absolute-p "~rms/foo")
     @result{} t
@end group
@group
(file-name-absolute-p "rms/foo")
     @result{} nil
@end group
@group
(file-name-absolute-p "/user/rms/foo")
     @result{} t
@end group
@end example
@end defun

@node File Name Expansion
@c @subsection Functions that Expand Filenames
@subsection $B%U%!%$%kL>$rE83+$9$k4X?t(B
@c @cindex expansion of file names
@cindex $B%U%!%$%kL>$rE83+$9$k4X?t(B

@c   @dfn{Expansion} of a file name means converting a relative file name
@c to an absolute one.  Since this is done relative to a default directory,
@c you must specify the default directory name as well as the file name to
@c be expanded.  Expansion also simplifies file names by eliminating
@c redundancies such as @file{./} and @file{@var{name}/../}.
$B%U%!%$%kL>$N(B@dfn{$BE83+(B}$B!J(Bexpansion$B!K$H$O!"(B
$BAjBP%U%!%$%kL>$r@dBP%U%!%$%kL>$KJQ49$9$k$3$H$G$9!#(B
$B$3$l$O%G%U%)%k%H%G%#%l%/%H%j$r4p=`$K9T$&$N$G!"(B
$BE83+$9$Y$-%U%!%$%kL>$K2C$($F!"%G%U%)%k%H%G%#%l%/%H%j$NL>A0$b(B
$B;XDj$9$kI,MW$,$"$j$^$9!#(B
$B$^$?!"E83+$G$O!"(B@file{./}$B$d(B@file{@var{name}/../}$B$N$h$&$J>iD9ItJ,$r(B
$B<h$j=|$$$F%U%!%$%kL>$rC1=c$K$7$^$9!#(B

@defun expand-file-name filename &optional directory
@c This function converts @var{filename} to an absolute file name.  If
@c @var{directory} is supplied, it is the default directory to start with
@c if @var{filename} is relative.  (The value of @var{directory} should
@c itself be an absolute directory name; it may start with @samp{~}.)
@c Otherwise, the current buffer's value of @code{default-directory} is
@c used.  For example:
$B$3$N4X?t$O(B@var{filename}$B$r@dBP%U%!%$%kL>$KJQ49$9$k!#(B
@var{directory}$B$,M?$($i$l$k$H!"(B
@var{filename}$B$,AjBP%U%!%$%kL>$G$"$l$P!"(B
$B%G%U%)%k%H%G%#%l%/%H%j$r4p=`$K$9$k!#(B
$B!J(B@var{directory}$B$NCM$=$N$b$N$O@dBP%G%#%l%/%H%jL>$G$"$k$3$H!#(B
@samp{~}$B$G;O$^$C$F$b$h$$!#!K(B
$B$5$b$J$1$l$P!"%P%C%U%!$N(B@code{default-directory}$B$NCM$r;H$&!#(B
$B$?$H$($P$D$.$N$H$*$j!#(B

@example
@group
(expand-file-name "foo")
     @result{} "/xcssun/users/rms/lewis/foo"
@end group
@group
(expand-file-name "../foo")
     @result{} "/xcssun/users/rms/foo"
@end group
@group
(expand-file-name "foo" "/usr/spool/")
     @result{} "/usr/spool/foo"
@end group
@group
(expand-file-name "$HOME/foo")
     @result{} "/xcssun/users/rms/lewis/$HOME/foo"
@end group
@end example

@c Filenames containing @samp{.} or @samp{..} are simplified to their
@c canonical form:
@samp{.}$B$d(B@samp{..}$B$r4^$`%U%!%$%kL>$O!"$=$l$i$N@5B'$J7A$KC1=c2=$9$k!#(B

@example
@group
(expand-file-name "bar/../foo")
     @result{} "/xcssun/users/rms/lewis/foo"
@end group
@end example

@c Note that @code{expand-file-name} does @emph{not} expand environment
@c variables; only @code{substitute-in-file-name} does that.
@code{expand-file-name}$B$O4D6-JQ?t$rE83+(B@emph{$B$7$J$$(B}$B$3$H$KCm0U!#(B
@code{substitute-in-file-name}$B$@$1$,$=$l$r9T$&!#(B
@end defun

@c Emacs 19 feature
@defun file-relative-name filename directory
@c This function does the inverse of expansion---it tries to return a
@c relative name that is equivalent to @var{filename} when interpreted
@c relative to @var{directory}.
$B$3$N4X?t$OE83+$N5UA`:n$r9T$&!#(B
$B$D$^$j!"(B@var{directory}$B$r4p=`$K2r<a$9$k$H(B
@var{filename}$B$HEy2A$K$J$kAjBPL>$rJV$9!#(B

@c On some operating systems, an absolute file name begins with a device
@c name.  On such systems, @var{filename} has no relative equivalent based
@c on @var{directory} if they start with two different device names.  In
@c this case, @code{file-relative-name} returns @var{filename} in absolute
@c form.
$B@dBP%U%!%$%kL>$,AuCVL>$G;O$^$k%7%9%F%`$b$"$k!#(B
$B$=$N$h$&$J%7%9%F%`$G$O!"(B@var{directory}$B$H(B@var{filename}$B$,(B
2$B$D$N0[$J$kAuCVL>$G;O$^$k$H!"(B
@var{filename}$B$KEy2A$J(B@var{directory}$B$r4p=`$K$7$?AjBPL>$O$J$$!#(B
$B$=$N$h$&$J>l9g!"(B@code{file-relative-name}$B$O(B
$B@dBPL>$N7A$G(B@var{filename}$B$rJV$9!#(B

@example
(file-relative-name "/foo/bar" "/foo/")
     @result{} "bar"
(file-relative-name "/foo/bar" "/hack/")
     @result{} "/foo/bar"
@end example
@end defun

@defvar default-directory
@c The value of this buffer-local variable is the default directory for the
@c current buffer.  It should be an absolute directory name; it may start
@c with @samp{~}.  This variable is buffer-local in every buffer.
$B$3$N%P%C%U%!%m!<%+%k$JJQ?t$NCM$O!"(B
$B%+%l%s%H%P%C%U%!$N%G%U%)%k%H%G%#%l%/%H%j$G$"$k!#(B
$B$3$l$O@dBP%G%#%l%/%H%jL>$G$"$k$3$H!#(B
@samp{~}$B$G;O$^$C$F$b$h$$!#(B
$B$3$NJQ?t$O3F%P%C%U%!$K$*$$$F%P%C%U%!%m!<%+%k$G$"$k!#(B

@c @code{expand-file-name} uses the default directory when its second
@c argument is @code{nil}.
@code{expand-file-name}$B$O!"$=$NBh(B2$B0z?t$,(B@code{nil}$B$G$"$k$H(B
$B%G%U%)%k%H%G%#%l%/%H%j$r;H$&!#(B

@c On Unix systems, the value is always a string ending with a slash.
UNIX$B$G$O!"$3$NCM$O$D$M$K%9%i%C%7%e$G=*$kJ8;zNs$G$"$k!#(B

@example
@group
default-directory
     @result{} "/user/lewis/manual/"
@end group
@end example
@end defvar

@defun substitute-in-file-name filename
@c This function replaces environment variables references in
@c @var{filename} with the environment variable values.  Following standard
@c Unix shell syntax, @samp{$} is the prefix to substitute an environment
@c variable value.
$B$3$N4X?t$O!"(B@var{filename}$BFb$N4D6-JQ?t$N;2>H$r(B
$B4D6-JQ?t$NCM$GCV$-49$($k!#(B
UNIX$B$N%7%'%k$N9=J85,B'$K=>$C$F!"(B
@samp{$}$B$O4D6-JQ?t$NCM$KCV49$9$k$?$a$N@\F,<-$G$"$k!#(B

@c The environment variable name is the series of alphanumeric characters
@c (including underscores) that follow the @samp{$}.  If the character following
@c the @samp{$} is a @samp{@{}, then the variable name is everything up to the
@c matching @samp{@}}.
$B4D6-JQ?tL>$O!"(B@samp{$}$B$KB3$/!J2<@~$r4^$`!K1Q?t;z$NNs$G$"$k!#(B
@samp{$}$B$N$D$.$NJ8;z$,(B@samp{@{}$B$G$"$k$H!"(B
$BBP1~$9$k(B@samp{@}}$B$^$G$,JQ?tL>$G$"$k!#(B

@c @c Wordy to avoid overfull hbox.  --rjc 15mar92
@c Here we assume that the environment variable @code{HOME}, which holds
@c the user's home directory name, has value @samp{/xcssun/users/rms}.
$B$3$3$G$O!"4D6-JQ?t(B@code{HOME}$B$O%f!<%6!<$N%[!<%`%G%#%l%/%H%jL>(B
@samp{/xcssun/users/rms}$B$rJ];}$7$F$$$k$H2>Dj$9$k!#(B

@example
@group
(substitute-in-file-name "$HOME/foo")
     @result{} "/xcssun/users/rms/foo"
@end group
@end example

@c After substitution, if a @samp{~} or a @samp{/} appears following a
@c @samp{/}, everything before the following @samp{/} is discarded:
$BCV498e!"(B@samp{/}$B$N$D$.$K(B@samp{~}$B$+(B@samp{/}$B$,8=$l$k$H!"(B
@samp{/}$B$^$G$NItJ,$r$9$Y$F<h$j=|$/!#(B

@example
@group
(substitute-in-file-name "bar/~/foo")
     @result{} "~/foo"
@end group
@group
(substitute-in-file-name "/usr/local/$HOME/foo")
     @result{} "/xcssun/users/rms/foo"
     ;; @r{@file{/usr/local/} has been discarded.}
@end group
@end example

@c On VMS, @samp{$} substitution is not done, so this function does nothing
@c on VMS except discard superfluous initial components as shown above.
VMS$B$G$O!"(B@samp{$}$B$K$h$kCV49$O9T$o$J$$$?$a!"(B
$B$3$N4X?t$O>iD9ItJ,$r<h$j=|$/0J30$K$O$J$K$b9T$o$J$$!#(B
@end defun

@node Unique File Names
@c @subsection Generating Unique File Names
@subsection $B0l0U$J%U%!%$%kL>$N@8@.(B

@c   Some programs need to write temporary files.  Here is the usual way to
@c construct a name for such a file:
$B0l;~E*$J%U%!%$%k$K=q$/I,MW$,$"$k%W%m%0%i%`$b$"$j$^$9!#(B
$B$=$N$h$&$J%U%!%$%k8~$1$NL>A0$r:n$kDL>o$NJ}K!$O$D$.$N$H$*$j$G$9!#(B

@example
(make-temp-name
 (expand-file-name @var{name-of-application}
                   temporary-file-directory))
@end example

@noindent
@c The job of @code{make-temp-name} is to prevent two different users or
@c two different jobs from trying to use the exact same file name.  This
@c example uses the variable @code{temporary-file-directory} to decide
@c where to put the temporary file.  All Emacs Lisp programs should
@c use @code{temporary-file-directory} for this purpose, to give the user
@c a uniform way to specify the directory for all temporary files.
@code{make-temp-name}$B$N;E;v$O!"(B
$B0[$J$k(B2$B?M$N%f!<%6!<$d0[$J$k(B2$B$D$N%8%g%V$,$^$C$?$/F1$8%U%!%$%kL>$r(B
$B;H$o$J$$$h$&$K$9$k$3$H$G$9!#(B
$B$3$NNc$G$O!"JQ?t(B@code{temporary-file-directory}$B$r;H$C$F(B
$B0l;~E*$J%U%!%$%k$rCV$/>l=j$r7h$a$F$$$^$9!#(B
$B$9$Y$F$N(BEmacs Lisp$B%W%m%0%i%`$G$O!"(B
$B$9$Y$F$N0l;~E*$J%U%!%$%k8~$1$N%G%#%l%/%H%j$r;XDj$9$k(B
$B0l0U$JJ}K!$r%f!<%6!<$KDs6!$9$k$?$a$K!"(B
$B$3$NL\E*$K$O(B@code{temporary-file-directory}$B$r;H$&$Y$-$G$9!#(B

@defun make-temp-name string
@c This function generates a string that can be used as a unique file name.
@c The name starts with @var{string}, and contains a number that is
@c different in each Emacs job.
$B$3$N4X?t$O!"0l0U$J%U%!%$%kL>$H$7$F;H$($kJ8;zNs$r@8@.$9$k!#(B
$BL>A0$O(B@var{string}$B$G;O$^$j!"3F(BEmacs$B%8%g%V$4$H$K0[$J$k?t$r4^$`!#(B

@example
@group
(make-temp-name "/tmp/foo")
     @result{} "/tmp/foo232J6v"
@end group
@end example

@c To prevent conflicts among different libraries running in the same
@c Emacs, each Lisp program that uses @code{make-temp-name} should have its
@c own @var{string}.  The number added to the end of @var{string}
@c distinguishes between the same application running in different Emacs
@c jobs.  Additional added characters permit a large number of distinct
@c names even in one Emacs job.
$BF1$8(BEmacs$B$GF0:n$7$F$$$k0[$J$k%i%$%V%i%j$N$"$$$@$G>WFM$7$J$$$h$&$K!"(B
@code{make-temp-name}$B$r;H$&3F(BLisp$B%W%m%0%i%`$G$O!"(B
$BFH<+$N(B@var{string}$B$r;H$&$Y$-$G$"$k!#(B
@var{string}$B$NKvHx$KIU2C$5$l$k?t$O!"(B
$B0[$J$k(BEmacs$B%8%g%V$GF0$$$F$$$kF1$8%"%W%j%1!<%7%g%s$r6hJL$9$k!#(B
$BJ8;z$rM>7W$KDI2C$9$k$3$H$G!"(B1$B$D$N(BEmacs$B%8%g%V$G$"$C$F$b(B
$B0[$J$kL>A0$N8D?t$rHs>o$KB?$/$G$-$k!#(B
@end defun

@defvar temporary-file-directory
@c @cindex @code{TMPDIR} environment variable.
@c @cindex @code{TMP} environment variable.
@cindex @code{TMPDIR}$B!"4D6-JQ?t(B
@cindex $B4D6-JQ?t(B@code{TMPDIR}
@cindex @code{TMP}$B!"4D6-JQ?t(B
@cindex $B4D6-JQ?t(B@code{TMP}
@c This variable specifies the directory name for creating temporary files.
@c Its value should be a directory name (@pxref{Directory Names}), but it
@c is good for Lisp programs to cope if the value is a directory's file
@c name instead.  Using the value as the second argument to
@c @code{expand-file-name} is a good way to achieve that.
$B$3$NJQ?t$O!"0l;~E*$J%U%!%$%k$r:n@.$9$k$?$a$N%G%#%l%/%H%jL>$r;XDj$9$k!#(B
$B$=$NCM$O%G%#%l%/%H%jL>!J(B@pxref{Directory Names}$B!K$G$"$k$Y$-$@$,!"(B
Lisp$B%W%m%0%i%`$K$H$C$F$O!"(B
$B$=$NCM$,%G%#%l%/%H%j$N%U%!%$%k$H$7$F$NL>A0$G$"$C$F$b=hM}$G$-$k$[$&$,$h$$!#(B
$B$3$NCM$r(B@code{expand-file-name}$B$NBh(B2$B0z?t$K;H$&$H!"(B
$B$=$N$h$&$K$G$-$k!#(B

@c The default value is determined in a reasonable way for your operating
@c system; on GNU and Unix systems it is based on the @code{TMP} and
@c @code{TMPDIR} environment variables.
$B%G%U%)%k%HCM$O!"FI<T$N%*%Z%l!<%F%#%s%0%7%9%F%`$K$*$$$F(B
$B9gM}E*$JJ}K!$G7hDj$5$l$k!#(B
GNU$B$H(BUNIX$B%7%9%F%`$G$O!"4D6-JQ?t(B@code{TMP}$B$d(B@code{TMPDIR}$B$r4p$K$9$k!#(B

@c Even if you do not use @code{make-temp-name} to choose the temporary
@c file's name, you should still use this variable to decide which
@c directory to put the file in.
$BFI<T$,0l;~E*$J%U%!%$%kL>$rA*$V$?$a$K(B@code{make-temp-name}$B$r(B
$B;H$o$J$$>l9g$G$"$C$F$b!"(B
$B0l;~E*$J%U%!%$%kL>$rCV$/%G%#%l%/%H%j$r7h$a$k$?$a$K(B
$B$3$NJQ?t$r;H$&$Y$-$G$"$k!#(B
@end defvar

@node File Name Completion
@c @subsection File Name Completion
@subsection $B%U%!%$%kL>$NJd40(B
@c @cindex file name completion subroutines
@c @cindex completion, file name
@cindex $B%U%!%$%kL>$NJd40%5%V%k!<%F%#%s(B
@cindex $BJd40!"%U%!%$%kL>(B

@c   This section describes low-level subroutines for completing a file
@c name.  For other completion functions, see @ref{Completion}.
$BK\@a$G$O!"%U%!%$%kL>$NJd408~$1$NDc%l%Y%k$N%5%V%k!<%F%#%s$K$D$$$F=R$Y$^$9!#(B
$BB>$NJd404X?t$K$D$$$F$O!"(B@ref{Completion}$B$r;2>H$7$F$/$@$5$$!#(B

@defun file-name-all-completions partial-filename directory
@c This function returns a list of all possible completions for a file
@c whose name starts with @var{partial-filename} in directory
@c @var{directory}.  The order of the completions is the order of the files
@c in the directory, which is unpredictable and conveys no useful
@c information.
$B$3$N4X?t$O!"%G%#%l%/%H%j(B@var{directory}$B$K$*$$$F(B
@var{partial-filename}$B$G;O$^$kL>A0$N%U%!%$%k$KBP$9$k(B
$B$9$Y$F$NJd408uJd$+$i@.$k%j%9%H$rJV$9!#(B
$B8uJd$N=gHV$O%G%#%l%/%H%jFb$G$N%U%!%$%k$N=gHV$G$"$j!"(B
$B$=$l$OM=B,$G$-$:M-MQ$J>pJs$O$J$K$b$J$$!#(B

@c The argument @var{partial-filename} must be a file name containing no
@c directory part and no slash.  The current buffer's default directory is
@c prepended to @var{directory}, if @var{directory} is not absolute.
$B0z?t(B@var{partial-filename}$B$O!"%G%#%l%/%H%jItJ,$d%9%i%C%7%e$r(B
$B$$$C$5$$4^$^$J$$%U%!%$%kL>$G$"$k$3$H!#(B
@var{directory}$B$,@dBPL>$G$J$$$H!"(B
$B%+%l%s%H%P%C%U%!$N%G%U%)%k%H%G%#%l%/%H%j$r(B@var{directory}$B$N$^$($KJd$&!#(B

@c In the following example, suppose that @file{~rms/lewis} is the current
@c default directory, and has five files whose names begin with @samp{f}:
@c @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
@c @file{file.c.~2~}.@refill
$B$D$.$NNc$G!"%+%l%s%H%G%U%)%k%H%G%#%l%/%H%j$O(B@file{~rms/lewis}$B$G$"$j!"(B
@samp{f}$B$G;O$^$kL>A0$N%U%!%$%k$O!"(B
@file{foo}$B!"(B@file{file~}$B!"(B@file{file.c}$B!"(B@file{file.c.~1~}$B!"(B
@file{file.c.~2~}$B$N(B5$B$D$G$"$k$H2>Dj$9$k!#(B

@example
@group
(file-name-all-completions "f" "")
     @result{} ("foo" "file~" "file.c.~2~" 
                "file.c.~1~" "file.c")
@end group

@group
(file-name-all-completions "fo" "")  
     @result{} ("foo")
@end group
@end example
@end defun

@defun file-name-completion filename directory
@c This function completes the file name @var{filename} in directory
@c @var{directory}.  It returns the longest prefix common to all file names
@c in directory @var{directory} that start with @var{filename}.
$B$3$N4X?t$O!"%G%#%l%/%H%j(B@var{directory}$B$K$*$$$F%U%!%$%kL>(B@var{filename}$B$r(B
$BJd40$9$k!#(B
$B%G%#%l%/%H%j(B@var{directory}$B$K$*$$$F(B@var{filename}$B$G;O$^$k(B
$B$9$Y$F$N%U%!%$%kL>$K6&DL$J:GD9$NJ8;zNs$rJV$9!#(B

@c If only one match exists and @var{filename} matches it exactly, the
@c function returns @code{t}.  The function returns @code{nil} if directory
@c @var{directory} contains no name starting with @var{filename}.
@var{filename}$B$G;O$^$k$b$N$,$?$C$?(B1$B$D$G$"$j40A4$K0lCW$9$k$H!"(B
$B$3$N4X?t$O(B@code{t}$B$rJV$9!#(B
$B%G%#%l%/%H%j(B@var{directory}$B$K(B@var{filename}$B$G;O$^$kL>A0$,$J$$$H(B
@code{nil}$B$rJV$9!#(B

@c In the following example, suppose that the current default directory
@c has five files whose names begin with @samp{f}: @file{foo},
@c @file{file~}, @file{file.c}, @file{file.c.~1~}, and
@c @file{file.c.~2~}.@refill
$B$D$.$NNc$G!"%+%l%s%H%G%U%)%k%H%G%#%l%/%H%j$K$O(B
@samp{f}$B$G;O$^$kL>A0$N%U%!%$%k$O!"(B
@file{foo}$B!"(B@file{file~}$B!"(B@file{file.c}$B!"(B@file{file.c.~1~}$B!"(B
@file{file.c.~2~}$B$N(B5$B$D$G$"$k$H2>Dj$9$k!#(B

@example
@group
(file-name-completion "fi" "")
     @result{} "file"
@end group

@group
(file-name-completion "file.c.~1" "")
     @result{} "file.c.~1~"
@end group

@group
(file-name-completion "file.c.~1~" "")
     @result{} t
@end group

@group
(file-name-completion "file.c.~3" "")
     @result{} nil
@end group
@end example
@end defun

@defopt completion-ignored-extensions
@c @code{file-name-completion} usually ignores file names that end in any
@c string in this list.  It does not ignore them when all the possible
@c completions end in one of these suffixes or when a buffer showing all
@c possible completions is displayed.@refill
@code{file-name-completion}$B$O!"$3$N%j%9%HFb$N$$$:$l$+$NJ8;zNs$G=*$k(B
$BL>A0$N%U%!%$%k$rDL>oL5;k$9$k!#(B
$BJd408uJd$9$Y$F$,$3$l$i$N@\F,<-$N(B1$B$D$G=*$k>l9g$d!"(B
$BJd408uJd$9$Y$F$r4^$s$@%P%C%U%!$,I=<($5$l$F$$$k>l9g$K$OL5;k$7$J$$!#(B

@c A typical value might look like this:
$BE57?E*$JCM$O$D$.$N$H$*$j$G$"$k!#(B

@example
@group
completion-ignored-extensions
     @result{} (".o" ".elc" "~" ".dvi")
@end group
@end example
@end defopt

@node Standard File Names
@c @subsection Standard File Names
@subsection $BI8=`%U%!%$%kL>(B

@c   Most of the file names used in Lisp programs are entered by the user.
@c But occasionally a Lisp program needs to specify a standard file name
@c for a particular use---typically, to hold customization information
@c about each user.  For example, abbrev definitions are stored (by
@c default) in the file @file{~/.abbrev_defs}; the @code{completion}
@c package stores completions in the file @file{~/.completions}.  These are
@c two of the many standard file names used by parts of Emacs for certain
@c purposes.
Lisp$B%W%m%0%i%`$G;H$o$l$k$[$H$s$I$N%U%!%$%kL>$O!"(B
$B%f!<%6!<$,F~NO$7$?$b$N$G$9!#(B
$B$7$+$7!"(BLisp$B%W%m%0%i%`$G$O!"(B
$BFCDjL\E*$NI8=`%U%!%$%kL>$r;XDj$9$kI,MW$,$"$k>l9g$,$"$j$^$9!#(B
$BE57?E*$K$O!"3F%f!<%6!<$4$H$N%+%9%?%^%$%:>pJs$rJ];}$9$k$b$N$G$9!#(B
$B$?$H$($P!">JN,7A$NDj5A$O!J%G%U%)%k%H$G$O!K(B
$B%U%!%$%k(B@file{~/.abbrev_defs}$B$KJ]B8$5$l$^$9!#(B
$B%Q%C%1!<%8(B@code{completion}$B$O!"(B
$BJd40>pJs$r%U%!%$%k(B@file{~/.completions}$B$KJ]B8$7$^$9!#(B
$B$3$l$i$O!"(BEmacs$B$GFCDjL\E*$K;H$o$l$kB?$/$NI8=`%U%!%$%kL>$N$&$A$N(B2$B$D$G$9!#(B

@c   Various operating systems have their own conventions for valid file
@c names and for which file names to use for user profile data.  A Lisp
@c program which reads a file using a standard file name ought to use, on
@c each type of system, a file name suitable for that system.  The function
@c @code{convert-standard-filename} makes this easy to do.
$B$5$^$6$^$J$N%*%Z%l!<%F%#%s%0%7%9%F%`$K$O!"(B
$B@5$7$$%U%!%$%kL>$d%f!<%6!<$N%W%m%U%#!<%k%G!<%?$K;H$&%U%!%$%kL>$K(B
$BFH<+$N47=,$,$"$j$^$9!#(B
$BI8=`%U%!%$%kL>$r;HMQ$9$k%U%!%$%k$rFI$_9~$`(BLisp$B%W%m%0%i%`$G$O!"(B
$B3F%7%9%F%`$4$H$KEv3:%7%9%F%`$KE,$7$?%U%!%$%kL>$r;H$&$Y$-$G$9!#(B
$B4X?t(B@code{convert-standard-filename}$B$O!"$3$l$r4JC1$K$7$^$9!#(B

@defun convert-standard-filename filename
@c This function alters the file name @var{filename} to fit the conventions
@c of the operating system in use, and returns the result as a new string.
$B$3$N4X?t$O!"%U%!%$%kL>(B@var{filename}$B$r;HMQ$7$F$$$k%*%Z%l!<%F%#%s%0%7%9%F%`(B
$B$N47=,$K=>$&$h$&$KJQ49$7!"?7$?$JJ8;zNs$H$7$F7k2L$rJV$9!#(B
@end defun

@c   The recommended way to specify a standard file name in a Lisp program
@c is to choose a name which fits the conventions of GNU and Unix systems,
@c usually with a nondirectory part that starts with a period, and pass it
@c to @code{convert-standard-filename} instead of using it directly.  Here
@c is an example from the @code{completion} package:
Lisp$B%W%m%0%i%`$K$*$$$FI8=`%U%!%$%kL>$r;XDj$9$k?d>)J}K!$O!"(B
GNU$B$H(BUNIX$B%7%9%F%`$N47=,$K=>$C$?L>A0$rA*$V$3$H$G$9!#(B
$B$D$^$j!"%T%j%*%I$G;O$^$kHs%G%#%l%/%H%jItJ,$rA*$S!"(B
$B$=$l$rD>@\;H$&$+$o$j$K(B@code{convert-standard-filename}$B$KEO$7$^$9!#(B
$B%Q%C%1!<%8(B@code{completion}$B$+$i$NNc$r$D$.$K<($7$^$9!#(B

@example
(defvar save-completions-file-name
        (convert-standard-filename "~/.completions")
  "*The file name to save completions to.")
@end example

@c   On GNU and Unix systems, and on some other systems as well,
@c @code{convert-standard-filename} returns its argument unchanged.  On
@c some other systems, it alters the name to fit the system's conventions.
GNU$B$H(BUNIX$B%7%9%F%`!"$*$h$S!"B>$N$$$/$D$+$N%7%9%F%`$G$O!"(B
@code{convert-standard-filename}$B$O0z?t$rL$JQ99$GJV$7$^$9!#(B
$BJL$N%7%9%F%`$G$O!"%7%9%F%`$N47=,$K=>$&$h$&$KL>A0$rJQ99$7$^$9!#(B

@c   For example, on MS-DOS the alterations made by this function include
@c converting a leading @samp{.}  to @samp{_}, converting a @samp{_} in the
@c middle of the name to @samp{.} if there is no other @samp{.}, inserting
@c a @samp{.} after eight characters if there is none, and truncating to
@c three characters after the @samp{.}.  (It makes other changes as well.)
@c Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
@c @file{.completions} becomes @file{_complet.ion}.
$B$?$H$($P!"(BMS-DOS$B$G$O$3$N4X?t$O!"@hF,$N(B@samp{.}$B$r(B@samp{_}$B$K!"(B
@samp{.}$B$,$I$3$K$b$J$1$l$PL>A0$NESCf$N(B@samp{_}$B$r(B@samp{.}$B$K!"(B
8$BJ8;zL\$N$&$7$m$K(B@samp{.}$B$,$J$1$l$P(B@samp{.}$B$rA^F~$7!"(B
@samp{.}$B0J9_$N(B3$BJ8;z$h$j$&$7$m$r@Z$j5M$a$k$J$I$r9T$$$^$9!#(B
$B!J$3$l0J30$K$bJQ99$9$k!#!K(B
$B$7$?$,$C$F!"(B@file{.abbrev_defs}$B$O(B@file{_abbrev.def}$B$H$J$j!"(B
@file{.completions}$B$O(B@file{_complet.ion}$B$H$J$j$^$9!#(B

@node Contents of Directories
@c @section Contents of Directories
@section $B%G%#%l%/%H%j$NFbMF(B
@c @cindex directory-oriented functions
@c @cindex file names in directory
@cindex $B%G%#%l%/%H%j8~$14X?t(B
@cindex $B%G%#%l%/%H%jFb$N%U%!%$%kL>(B

@c   A directory is a kind of file that contains other files entered under
@c various names.  Directories are a feature of the file system.
$B%G%#%l%/%H%j$O!"$5$^$6$^$JL>A0$GF~$l$?JL$N%U%!%$%k$r(B
$B<}$a$F$$$k%U%!%$%k$N0l<o$G$9!#(B
$B%G%#%l%/%H%j$O!"%U%!%$%k%7%9%F%`$N5!G=$G$9!#(B

@c   Emacs can list the names of the files in a directory as a Lisp list,
@c or display the names in a buffer using the @code{ls} shell command.  In
@c the latter case, it can optionally display information about each file,
@c depending on the options passed to the @code{ls} command.
Emacs$B$O!"%G%#%l%/%H%jFb$N%U%!%$%kL>$r(BLisp$B$N%j%9%H$H$7$F0lMw$K$7$?$j!"(B
$B%7%'%k%3%^%s%I(B@code{ls}$B$r;H$C$F%P%C%U%!$KL>A0$rI=<($G$-$^$9!#(B
$B8e<T$N>l9g!"%3%^%s%I(B@code{ls}$B$KEO$7$?%*%W%7%g%s$K1~$8$F!"(B
$B3F%U%!%$%k$K4X$9$k>pJs$bI=<($G$-$^$9!#(B

@defun directory-files directory &optional full-name match-regexp nosort
@c This function returns a list of the names of the files in the directory
@c @var{directory}.  By default, the list is in alphabetical order.
$B$3$N4X?t$O!"%G%#%l%/%H%j(B@var{directory}$BFb$N(B
$B%U%!%$%k$NL>A0$+$i@.$k%j%9%H$rJV$9!#(B
$B%G%U%)%k%H$G$O!"%j%9%H$O%"%k%U%!%Y%C%H=g$K$J$k!#(B

@c If @var{full-name} is non-@code{nil}, the function returns the files'
@c absolute file names.  Otherwise, it returns the names relative to
@c the specified directory.
@var{full-name}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B4X?t$O%U%!%$%k$N@dBP%U%!%$%kL>$rJV$9!#(B
$B$5$b$J$1$l$P!";XDj$7$?%G%#%l%/%H%j$KBP$9$kAjBPL>$rJV$9!#(B

@c If @var{match-regexp} is non-@code{nil}, this function returns only
@c those file names that contain a match for that regular expression---the
@c other file names are excluded from the list.
@var{match-regexp}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B$3$N4X?t$O@55,I=8=(B@var{match-regexp}$B$K0lCW$9$k%U%!%$%kL>$N$_$rJV$9!#(B
$B$D$^$j!"B>$NL>A0$N%U%!%$%k$O%j%9%H$+$i=|$+$l$k!#(B

@c @c Emacs 19 feature
@c If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
@c the list, so you get the file names in no particular order.  Use this if
@c you want the utmost possible speed and don't care what order the files
@c are processed in.  If the order of processing is visible to the user,
@c then the user will probably be happier if you do sort the names.
@var{nosort}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
@code{directory-files}$B$O%j%9%H$r%=!<%H$7$J$$$N$G!"(B
$B%U%!%$%kL>$N=gHV$K5,B'$O$J$$!#(B
$B=hM}B.EY$r:GBg$K$7$F%U%!%$%k$N=hM}=g=x$K94$i$J$$$J$i$P!"$3$l$rMQ$$$k!#(B
$B=hM}=g=x$,%f!<%6!<$K8+$($k>l9g$K$O!"(B
$B%=!<%H$7$?$[$&$,%f!<%6!<$O9,$;$G$"$m$&!#(B

@example
@group
(directory-files "~lewis")
     @result{} ("#foo#" "#foo.el#" "." ".."
         "dired-mods.el" "files.texi" 
         "files.texi.~1~")
@end group
@end example

@c An error is signaled if @var{directory} is not the name of a directory
@c that can be read.
@var{directory}$B$,FI$a$J$$%G%#%l%/%H%j$NL>A0$G$"$k$H%(%i!<$rDLCN$9$k!#(B
@end defun

@defun file-name-all-versions file dirname
@c This function returns a list of all versions of the file named
@c @var{file} in directory @var{dirname}.
$B$3$N4X?t$O!"%G%#%l%/%H%j(B@var{dirname}$BFb$N(B@var{file}$B$H$$$&L>A0$N(B
$B%U%!%$%k$N$9$Y$F$NHG$+$i@.$k%j%9%H$rJV$9!#(B
@end defun

@defun insert-directory file switches &optional wildcard full-directory-p
@c This function inserts (in the current buffer) a directory listing for
@c directory @var{file}, formatted with @code{ls} according to
@c @var{switches}.  It leaves point after the inserted text.
$B$3$N4X?t$O!"(B@code{ls}$B$K(B@var{switches}$B$rEO$7$FI=<($7$?(B
$B%G%#%l%/%H%j(B@var{file}$B$N0lMw$r!J%+%l%s%H%P%C%U%!$K!KA^F~$9$k!#(B
$B%]%$%s%H$OA^F~$7$?%F%-%9%H$N$&$7$m$KCV$+$l$k!#(B

@c The argument @var{file} may be either a directory name or a file
@c specification including wildcard characters.  If @var{wildcard} is
@c non-@code{nil}, that means treat @var{file} as a file specification with
@c wildcards.
$B0z?t(B@var{file}$B$O!"%G%#%l%/%H%jL>$G$"$k$+(B
$B%o%$%k%I%+!<%I$r4^$s$@%U%!%$%k;XDj$G$"$k!#(B
@var{wildcard}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
@var{file}$B$r%o%$%k%I%+!<%I$r4^$`%U%!%$%k;XDj$H$7$F07$&!#(B

@c If @var{full-directory-p} is non-@code{nil}, that means the directory
@c listing is expected to show the full contents of a directory.  You
@c should specify @code{t} when @var{file} is a directory and switches do
@c not contain @samp{-d}.  (The @samp{-d} option to @code{ls} says to
@c describe a directory itself as a file, rather than showing its
@c contents.)
@var{full-directory-p}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B%G%#%l%/%H%j0lMw$O%G%#%l%/%H%j$NA4FbMF$rI=$9$H2>Dj$9$k$3$H$r0UL#$9$k!#(B
@var{file}$B$,%G%#%l%/%H%j$G$"$j(B@var{switches}$B$K(B@samp{-d}$B$r4^$^$J$$>l9g$K$O!"(B
@code{t}$B$r;XDj$9$Y$-$G$"$k!#(B
$B!J(B@code{ls}$B$N%*%W%7%g%s(B@samp{-d}$B$O!"(B
$B%G%#%l%/%H%j$NFbMF$G$O$J$/!"%U%!%$%k$H$7$F$N%G%#%l%/%H%j<+?H$r(B
$BI=<($9$k$3$H$r0UL#$9$k!#!K(B

@c This function works by running a directory listing program whose name is
@c in the variable @code{insert-directory-program}.  If @var{wildcard} is
@c non-@code{nil}, it also runs the shell specified by
@c @code{shell-file-name}, to expand the wildcards.
$B$3$N4X?t$O!"JQ?t(B@code{insert-directory-program}$B$G;XDj$5$l$k(B
$BL>A0$N%G%#%l%/%H%jI=<(%W%m%0%i%`$r<B9T$7$FF0:n$9$k!#(B
@var{wildcard}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B%o%$%k%I%+!<%I$rE83+$9$k$?$a$K(B@code{shell-file-name}$B$G;XDj$5$l$k(B
$B%7%'%k$r<B9T$9$k!#(B
@end defun

@defvar insert-directory-program
@c This variable's value is the program to run to generate a directory listing
@c for the function @code{insert-directory}.
$B$3$NJQ?t$NCM$O!"4X?t(B@code{insert-directory}$B$G(B
$B%G%#%l%/%H%j0lMw$r@8@.$9$k$?$a$K<B9T$9$k%W%m%0%i%`$G$"$k!#(B
@end defvar

@node Create/Delete Dirs
@c @section Creating and Deleting Directories
@section $B%G%#%l%/%H%j$N:n@.$H:o=|(B
@c Emacs 19 features

@c   Most Emacs Lisp file-manipulation functions get errors when used on
@c files that are directories.  For example, you cannot delete a directory
@c with @code{delete-file}.  These special functions exist to create and
@c delete directories.
Emacs Lisp$B$N$[$H$s$I$N%U%!%$%kA`:n4X?t$O!"(B
$B%G%#%l%/%H%j$G$"$k%U%!%$%k$K;H$&$H%(%i!<$K$J$j$^$9!#(B
$B$?$H$($P!"(B@code{delete-file}$B$G$O%G%#%l%/%H%j$r:o=|$G$-$^$;$s!#(B
$B$3$l$i$NFCJL$J4X?t$O%G%#%l%/%H%j$r:n@.$7$?$j:o=|$9$k$?$a$N$b$N$G$9!#(B

@defun make-directory dirname
@c This function creates a directory named @var{dirname}.
$B$3$N4X?t$O(B@var{dirname}$B$H$$$&L>A0$N%G%#%l%/%H%j$r:n$k!#(B
@end defun

@defun delete-directory dirname
@c This function deletes the directory named @var{dirname}.  The function
@c @code{delete-file} does not work for files that are directories; you
@c must use @code{delete-directory} for them.  If the directory contains
@c any files, @code{delete-directory} signals an error.
$B$3$N4X?t$O!"%G%#%l%/%H%j(B@var{dirname}$B$r:o=|$9$k!#(B
$B4X?t(B@code{delete-file}$B$O!"%G%#%l%/%H%j$G$"$k%U%!%$%k$K$O;H$($J$$!#(B
$B%G%#%l%/%H%j$K$O(B@code{delete-directory}$B$r;H$&I,MW$,$"$k!#(B
$B%G%#%l%/%H%jFb$K%U%!%$%k$,$"$k$H!"(B@code{delete-directory}$B$O(B
$B%(%i!<$rDLCN$9$k!#(B
@end defun

@node Magic File Names
@c @section Making Certain File Names ``Magic''
@section $B%U%!%$%kL>$r!X%^%8%C%/!Y$K$9$k(B
@c @cindex magic file names
@cindex $B%^%8%C%/%U%!%$%kL>(B

@c @c Emacs 19 feature
@c   You can implement special handling for certain file names.  This is
@c called making those names @dfn{magic}.  The principal use for this
@c feature is in implementing remote file names (@pxref{Remote Files,,
@c Remote Files, emacs, The GNU Emacs Manual}).
$BFCDj$N%U%!%$%kL>$rFCJL$K07$&$3$H$,$G$-$^$9!#(B
$B$3$l$r$=$l$i$NL>A0$r(B@dfn{$B%^%8%C%/(B}$B!J(Bmagic$B!K$K$9$k$H$$$$$^$9!#(B
$B$3$N5!G=$N<g$JMQES$O%j%b!<%H%U%!%$%kL>(B
$B!J(B@pxref{Remote Files,, $B%j%b!<%H%U%!%$%k(B, emacs, GNU Emacs $B%^%K%e%"%k(B}$B!K(B
$B$r<BAu$9$k$3$H$G$9!#(B

@c   To define a kind of magic file name, you must supply a regular
@c expression to define the class of names (all those that match the
@c regular expression), plus a handler that implements all the primitive
@c Emacs file operations for file names that do match.
$B%^%8%C%/%U%!%$%kL>$N<oN`$rDj5A$9$k$K$O!"(B
$BL>A0$N%/%i%9!J@55,I=8=$K0lCW$9$k$b$N$9$Y$F!K$rDj5A$9$k@55,I=8=$H!"(B
$B$=$l$K0lCW$9$k%U%!%$%k$KBP$9$k(B
Emacs$B$N4pK\%U%!%$%kA`:n$r<BAu$9$k%O%s%I%i$r;XDj$9$kI,MW$,$"$j$^$9!#(B

@c   The variable @code{file-name-handler-alist} holds a list of handlers,
@c together with regular expressions that determine when to apply each
@c handler.  Each element has this form:
$BJQ?t(B@code{file-name-handler-alist}$B$O!"(B
$B%O%s%I%i$HEv3:%O%s%I%i$NE,MQ$r7hDj$9$k@55,I=8=$+$i$J$k%j%9%H$rJ];}$7$^$9!#(B
$B3FMWAG$N7A$O$D$.$N$H$*$j$G$9!#(B

@example
(@var{regexp} . @var{handler})
@end example

@noindent
@c All the Emacs primitives for file access and file name transformation
@c check the given file name against @code{file-name-handler-alist}.  If
@c the file name matches @var{regexp}, the primitives handle that file by
@c calling @var{handler}.
Emacs$B$N$9$Y$F$N%U%!%$%kA`:n4pK\4X?t$H%U%!%$%kL>JQ494pK\4X?t$O!"(B
$B;XDj$5$l$?L>A0$r(B@code{file-name-handler-alist}$B$KBP$7$F8!::$7$^$9!#(B
$B%U%!%$%kL>$,(B@var{regexp}$B$K0lCW$9$k$H!"(B
$B4pK\4X?t$O(B@var{handler}$B$r8F$S=P$7$FEv3:%U%!%$%k$r=hM}$7$^$9!#(B

@c The first argument given to @var{handler} is the name of the primitive;
@c the remaining arguments are the arguments that were passed to that
@c operation.  (The first of these arguments is typically the file name
@c itself.)  For example, if you do this:
@var{handler}$B$KM?$($k:G=i$N0z?t$O4pK\4X?t$NL>A0$G$9!#(B
$B;D$j$N0z?t$OEv3:A`:n$KEO$5$l$k$Y$-0z?t$G$9!#(B
$B!J$=$l$i$N0z?t$N:G=i$N$b$N$OE57?E*$K$O%U%!%$%kL><+?H$G$"$k!#!K(B
$B$?$H$($P!"$D$.$N$h$&$K$7$?>l9g!"(B

@example
(file-exists-p @var{filename})
@end example

@noindent
@c and @var{filename} has handler @var{handler}, then @var{handler} is
@c called like this:
@var{filename}$B$K%O%s%I%i(B@var{handler}$B$,$"$k$H!"(B
@var{handler}$B$O$D$.$N$h$&$K8F$S=P$5$l$^$9!#(B

@example
(funcall @var{handler} 'file-exists-p @var{filename})
@end example

@c Here are the operations that a magic file name handler gets to handle:
$B$D$.$O!"%^%8%C%/%U%!%$%kL>$N%O%s%I%i$,=hM}$9$Y$-A`:n$G$9!#(B

@ifinfo
@noindent
@c @code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
@c @code{delete-file},
@c @code{diff-latest-backup-file},
@c @code{directory-file-name},
@c @code{directory-files},
@c @code{dired-call-process},
@c @code{dired-compress-file}, @code{dired-uncache},
@c @code{expand-file-name},
@c @code{file-accessible-directory-p},@*
@c @code{file-attributes},
@c @code{file-directory-p},
@c @code{file-executable-p}, @code{file-exists-p},@*
@c @code{file-local-copy},
@c @code{file-modes}, @code{file-name-all-completions},@*
@c @code{file-name-as-directory},
@c @code{file-name-completion},
@c @code{file-name-directory},
@c @code{file-name-nondirectory},
@c @code{file-name-sans-versions}, @code{file-newer-than-file-p},
@c @code{file-ownership-preserved-p},
@c @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
@c @code{file-truename}, @code{file-writable-p},
@c @code{find-backup-file-name},
@c @code{get-file-buffer},@*
@c @code{insert-directory},
@c @code{insert-file-contents},
@c @code{load}, @code{make-directory},
@c @code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
@c @code{set-visited-file-modtime}, @code{shell-command},@*
@c @code{unhandled-file-name-directory},
@c @code{vc-registered},
@c @code{verify-visited-file-modtime},@*
@c @code{write-region}.
@code{add-name-to-file}$B!"(B@code{copy-file}$B!"(B@code{delete-directory}$B!"(B
@code{delete-file}$B!"(B
@code{diff-latest-backup-file}$B!"(B
@code{directory-file-name}$B!"(B
@code{directory-files}$B!"(B
@code{dired-call-process}$B!"(B
@code{dired-compress-file}$B!"(B@code{dired-uncache}$B!"(B
@code{expand-file-name}$B!"(B
@code{file-accessible-directory-p}$B!"(B@*
@code{file-attributes}$B!"(B
@code{file-directory-p}$B!"(B
@code{file-executable-p}$B!"(B@code{file-exists-p}$B!"(B@*
@code{file-local-copy}$B!"(B
@code{file-modes}$B!"(B@code{file-name-all-completions}$B!$(B@*
@code{file-name-as-directory}$B!"(B
@code{file-name-completion}$B!"(B
@code{file-name-directory}$B!"(B
@code{file-name-nondirectory}$B!"(B
@code{file-name-sans-versions}$B!"(B@code{file-newer-than-file-p}$B!"(B
@code{file-ownership-preserved-p}$B!"(B
@code{file-readable-p}$B!"(B@code{file-regular-p}$B!"(B@code{file-symlink-p}$B!"(B
@code{file-truename}$B!"(B@code{file-writable-p}$B!"(B
@code{find-backup-file-name}$B!"(B
@code{get-file-buffer}$B!"(B@*
@code{insert-directory}$B!"(B
@code{insert-file-contents}$B!"(B
@code{load}, @code{make-directory}$B!"(B
@code{make-symbolic-link}$B!"(B@code{rename-file}$B!"(B@code{set-file-modes}$B!"(B
@code{set-visited-file-modtime}$B!"(B@code{shell-command}$B!"(B@*
@code{unhandled-file-name-directory}$B!"(B
@code{vc-registered}$B!"(B
@code{verify-visited-file-modtime}$B!"(B@*
@code{write-region}$B!#(B
@end ifinfo
@iftex
@noindent
@c @code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
@c @code{delete-file},
@c @code{diff-latest-backup-file},
@c @code{directory-file-name},
@c @code{directory-files},
@c @code{dired-call-process},
@c @code{dired-compress-file}, @code{dired-uncache},
@c @code{expand-file-name},
@c @code{file-accessible-direc@discretionary{}{}{}tory-p},
@c @code{file-attributes},
@c @code{file-direct@discretionary{}{}{}ory-p},
@c @code{file-executable-p}, @code{file-exists-p},
@c @code{file-local-copy},
@c @code{file-modes}, @code{file-name-all-completions},
@c @code{file-name-as-directory},
@c @code{file-name-completion},
@c @code{file-name-directory},
@c @code{file-name-nondirec@discretionary{}{}{}tory},
@c @code{file-name-sans-versions}, @code{file-newer-than-file-p},
@c @code{file-ownership-pre@discretionary{}{}{}served-p},
@c @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
@c @code{file-truename}, @code{file-writable-p},
@c @code{find-backup-file-name},
@c @code{get-file-buffer},
@c @code{insert-directory},
@c @code{insert-file-contents},
@c @code{load}, @code{make-direc@discretionary{}{}{}tory},
@c @code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
@c @code{set-visited-file-modtime}, @code{shell-command},
@c @code{unhandled-file-name-directory},
@c @code{vc-regis@discretionary{}{}{}tered},
@c @code{verify-visited-file-modtime},
@c @code{write-region}.
@code{add-name-to-file}$B!"(B@code{copy-file}$B!"(B@code{delete-directory}$B!"(B
@code{delete-file}$B!"(B
@code{diff-latest-backup-file}$B!"(B
@code{directory-file-name}$B!"(B
@code{directory-files}$B!"(B
@code{dired-call-process}$B!"(B
@code{dired-compress-file}$B!"(B@code{dired-uncache}$B!"(B
@code{expand-file-name}$B!"(B
@code{file-accessible-direc@discretionary{}{}{}tory-p}$B!"(B
@code{file-attributes}$B!"(B
@code{file-direct@discretionary{}{}{}ory-p}$B!"(B
@code{file-executable-p}$B!"(B@code{file-exists-p}$B!"(B
@code{file-local-copy}$B!"(B
@code{file-modes}$B!"(B@code{file-name-all-completions}$B!"(B
@code{file-name-as-directory}$B!"(B
@code{file-name-completion}$B!"(B
@code{file-name-directory}$B!"(B
@code{file-name-nondirec@discretionary{}{}{}tory}$B!"(B
@code{file-name-sans-versions}$B!"(B@code{file-newer-than-file-p}$B!"(B
@code{file-ownership-pre@discretionary{}{}{}served-p}$B!"(B
@code{file-readable-p}$B!"(B@code{file-regular-p}$B!"(B@code{file-symlink-p}$B!"(B
@code{file-truename}$B!"(B@code{file-writable-p}$B!"(B
@code{find-backup-file-name}$B!"(B
@code{get-file-buffer}$B!"(B
@code{insert-directory}$B!"(B
@code{insert-file-contents}$B!"(B
@code{load}$B!"(B@code{make-direc@discretionary{}{}{}tory}$B!"(B
@code{make-symbolic-link}$B!"(B@code{rename-file}$B!"(B@code{set-file-modes}$B!"(B
@code{set-visited-file-modtime}$B!"(B@code{shell-command}$B!"(B
@code{unhandled-file-name-directory}$B!"(B
@code{vc-regis@discretionary{}{}{}tered}$B!"(B
@code{verify-visited-file-modtime}$B!"(B
@code{write-region}$B!#(B
@end iftex

@c Handlers for @code{insert-file-contents} typically need to clear the
@c buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
@c @var{visit} argument is non-@code{nil}.  This also has the effect of
@c unlocking the buffer if it is locked.
@code{insert-file-contents}$B$KBP$9$k%O%s%I%i$O!"(B
$B0z?t(B@var{visit}$B$,(B@code{nil}$B0J30$G$"$k$H$-$K$O(B
@code{(set-buffer-modified-p nil)}$B$r;H$C$F(B
$B%P%C%U%!$NJQ99%U%i%0$r%/%j%"$9$kI,MW$,E57?E*$K$O$"$j$^$9!#(B

@c The handler function must handle all of the above operations, and
@c possibly others to be added in the future.  It need not implement all
@c these operations itself---when it has nothing special to do for a
@c certain operation, it can reinvoke the primitive, to handle the
@c operation ``in the usual way''.  It should always reinvoke the primitive
@c for an operation it does not recognize.  Here's one way to do this:
$B%O%s%I%i4X?t$O!">e$N$9$Y$F$NA`:n!"$J$i$S$K!"(B
$B>-MhDI2C$5$l$k$b$N$r07$($kI,MW$,$"$j$^$9!#(B
$B$3$l$i$NA`:n$9$Y$F$r%O%s%I%i<+?H$G<BAu$9$kI,MW$O$"$j$^$;$s!#(B
$BFCDj$NA`:n$K$D$$$FFCJL$J$3$H$r9T$&I,MW$,$J$1$l$P!"(B
$B!XDL>o$I$*$j$K!YA`:n$r=hM}$9$k$?$a$K4pK\4X?t$r:F5/F0$G$-$^$9!#(B
$B%O%s%I%i$,G'<1$G$-$J$$A`:n$K$D$$$F$O!"(B
$B4pK\4X?t$r:F5/F0$9$k$Y$-$G$9!#(B
1$B$D$NJ}K!$O$D$.$N$H$*$j$G$9!#(B

@smallexample
(defun my-file-handler (operation &rest args)
@c   ;; @r{First check for the specific operations}
@c   ;; @r{that we have special handling for.}
  ;; @r{$B$^$:!"FCJL$K07$&I,MW$,$"$kA`:n$+$I$&$+8!::$9$k(B}
  (cond ((eq operation 'insert-file-contents) @dots{})
        ((eq operation 'write-region) @dots{})
        @dots{}
@c         ;; @r{Handle any operation we don't know about.}
        ;; @r{$BCN$i$J$$A`:n$r07$&(B}
        (t (let ((inhibit-file-name-handlers
                  (cons 'my-file-handler 
                        (and (eq inhibit-file-name-operation operation)
                             inhibit-file-name-handlers)))
                 (inhibit-file-name-operation operation))
             (apply operation args)))))
@end smallexample

@c When a handler function decides to call the ordinary Emacs primitive for
@c the operation at hand, it needs to prevent the primitive from calling
@c the same handler once again, thus leading to an infinite recursion.  The
@c example above shows how to do this, with the variables
@c @code{inhibit-file-name-handlers} and
@c @code{inhibit-file-name-operation}.  Be careful to use them exactly as
@c shown above; the details are crucial for proper behavior in the case of
@c multiple handlers, and for operations that have two file names that may
@c each have handlers.
$B%O%s%I%i4X?t$G!";XDj$5$l$?A`:n$K$D$$$F$O(BEmacs$B$NDL>o$N4pK\4X?t$r8F$S=P$9$H(B
$B7hDj$7$?$H$-$K$O!"4pK\4X?t$+$iF1$8%O%s%I%i$,:FEY8F$P$l$F(B
$BL58B:F5"$K$J$k$3$H$rKI$0I,MW$,$"$j$^$9!#(B
$B>e$NNc$O!"JQ?t(B@code{inhibit-file-name-handlers}$B$H(B
@code{inhibit-file-name-operation}$B$r;H$C$F$3$l$r9T$&J}K!$r<($9$b$N$G$9!#(B
$B$=$l$i$r>e$K<($7$?$H$*$j$K;H$&$h$&$KCm0U$7$F$/$@$5$$!#(B
$BJ#?t$N%O%s%I%i$,$"$C$?$j!"(B
2$B$D$N%U%!%$%k$r07$&A`:n$K$*$$$F3F%U%!%$%k$K%O%s%I%i$,$"$k>l9g$K$O!"(B
$B$3$N>\:Y$O=EMW$G$9!#(B

@defvar inhibit-file-name-handlers
@c This variable holds a list of handlers whose use is presently inhibited
@c for a certain operation.
$B$3$NJQ?t$O!"FCDjA`:n$K$D$$$F$O(B
$B8=:_E,MQ$r6X;_$5$l$F$$$k%O%s%I%i$N%j%9%H$rJ];}$9$k!#(B
@end defvar

@defvar inhibit-file-name-operation
@c The operation for which certain handlers are presently inhibited.
$BFCDj$N%O%s%I%i$K$*$$$F8=:_6X;_$5$l$F$$$kA`:n!#(B
@end defvar

@defun find-file-name-handler file operation
@c This function returns the handler function for file name @var{file}, or
@c @code{nil} if there is none.  The argument @var{operation} should be the
@c operation to be performed on the file---the value you will pass to the
@c handler as its first argument when you call it.  The operation is needed
@c for comparison with @code{inhibit-file-name-operation}.
$B$3$N4X?t$O%U%!%$%kL>(B@var{file}$B$KBP$9$k%O%s%I%i4X?t$rJV$9!#(B
$B%O%s%I%i$,$J$1$l$P(B@code{nil}$B$rJV$9!#(B
$B0z?t(B@var{operation}$B$O!"%U%!%$%k$KBP$7$FE,MQ$9$kA`:n$G$"$k$3$H!#(B
$B$D$^$j!"%O%s%I%i$r8F$S=P$9$H$-$KBh(B1$B0z?t$H$7$FEO$5$l$kCM!#(B
$BEv3:A`:n$O(B@code{inhibit-file-name-operation}$B$HHf3S$9$kI,MW$,$"$k!#(B
@end defun

@defun file-local-copy filename
@c This function copies file @var{filename} to an ordinary non-magic file,
@c if it isn't one already.
$B$3$N4X?t$O!"%U%!%$%k(B@var{filename}$B$,%^%8%C%/$G$J$$IaDL$N%U%!%$%k$G$J$1$l$P!"(B
@var{filename}$B$r%^%8%C%/$G$J$$IaDL$N%U%!%$%k$K%3%T!<$9$k!#(B

@c If @var{filename} specifies a magic file name, which programs
@c outside Emacs cannot directly read or write, this copies the contents to
@c an ordinary file and returns that file's name.
@var{filename}$B$,!"(B
Emacs$B$N30B&$N%W%m%0%i%`$+$i$OD>@\FI$s$@$j=q$1$J$$%^%8%C%/%U%!%$%kL>$G$"$k$H!"(B
$B$3$N4X?t$OIaDL$N%U%!%$%k$K%3%T!<$7$F$=$N%U%!%$%k$NL>A0$rJV$9!#(B

@c If @var{filename} is an ordinary file name, not magic, then this function
@c does nothing and returns @code{nil}.
@var{filename}$B$,IaDL$N%U%!%$%kL>$G%^%8%C%/$G$J$1$l$P!"(B
$B$3$N4X?t$O$J$K$b$;$:$K(B@code{nil}$B$rJV$9!#(B
@end defun

@defun unhandled-file-name-directory filename
@c This function returns the name of a directory that is not magic.  It
@c uses the directory part of @var{filename} if that is not magic.  For a
@c magic file name, it invokes the file name handler, which therefore
@c decides what value to return.
$B$3$N4X?t$O!"%^%8%C%/$G$O$J$$%G%#%l%/%H%j$NL>A0$rJV$9!#(B
@var{filename}$B$,%^%8%C%/$G$J$1$l$P!"(B
@var{filename}$B$N%G%#%l%/%H%jItJ,$r;H$&!#(B
$B%^%8%C%/%U%!%$%kL>$G$"$k$H!"%U%!%$%kL>%O%s%I%i$r5/F0$7!"(B
$BEv3:%O%s%I%i$,$I$s$JCM$rJV$9$+7hDj$9$k!#(B

@c This is useful for running a subprocess; every subprocess must have a
@c non-magic directory to serve as its current directory, and this function
@c is a good way to come up with one.
$B$3$l$O<B9TCf$N%5%V%W%m%;%9$KM-MQ$G$"$k!#(B
$B3F%5%V%W%m%;%9$K$O!"%+%l%s%H%G%#%l%/%H%j$H$7$F%^%8%C%/$G$J$$%G%#%l%/%H%j$,(B
$BI,MW$G$"$j!"$3$N4X?t$O$=$l$r07$&$N$K$h$$J}K!$G$"$k!#(B
@end defun

@node Format Conversion
@c @section File Format Conversion
@section $B%U%!%$%k=q<0JQ49(B

@c @cindex file format conversion
@c @cindex encoding file formats
@c @cindex decoding file formats
@cindex $B%U%!%$%k=q<0JQ49(B
@cindex $B%U%!%$%k=q<0$NId9f2=(B
@cindex $B%U%!%$%k=q<0$NI|9f2=(B
@c   The variable @code{format-alist} defines a list of @dfn{file formats},
@c which describe textual representations used in files for the data (text,
@c text-properties, and possibly other information) in an Emacs buffer.
@c Emacs performs format conversion if appropriate when reading and writing
@c files.
$BJQ?t(B@code{format-alist}$B$O!"(B
Emacs$B%P%C%U%!Fb$N%G!<%?!J%F%-%9%H!"%F%-%9%HB0@-!"$=$NB>$N>pJs!K$r(B
$B%U%!%$%kFb$G%F%-%9%HI=8=$9$kJ}K!$r5-=R$7$?(B
@dfn{$B%U%!%$%k=q<0(B}$B!J(Bfile format$B!K$N%j%9%H$rDj5A$7$^$9!#(B
Emacs$B$O%U%!%$%k$rFI$_=q$-$9$k$H$-$KI,MW$J$i$P=q<0JQ49$r9T$$$^$9!#(B

@defvar format-alist
@c This list contains one format definition for each defined file format.
$B$3$N%j%9%H$O!"3F%U%!%$%k=q<0$NDj5A$r4^$s$@%j%9%H$G$"$k!#(B
@end defvar

@c @cindex format definition
@cindex $B=q<0Dj5A(B
@c Each format definition is a list of this form:
$B3F=q<0Dj5A$O$D$.$N7A$N%j%9%H$G$9!#(B

@example
(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
@end example

@c Here is what the elements in a format definition mean:
$B=q<0Dj5A$N3FMWAG$N0UL#$O$D$.$N$H$*$j$G$9!#(B

@table @var
@item name
@c The name of this format.
$BEv3:=q<0$NL>A0!#(B

@item doc-string
@c A documentation string for the format.
$BEv3:=q<0$N@bL@J8;zNs!#(B

@item regexp
@c A regular expression which is used to recognize files represented in
@c this format.
$BEv3:=q<0$GI=8=$5$l$?%U%!%$%k$rG'<1$9$k$?$a$K;HMQ$9$k@55,I=8=!#(B

@item from-fn
@c A shell command or function to decode data in this format (to convert
@c file data into the usual Emacs data representation).
$BEv3:=q<0$N%G!<%?$rI|9f2=!J%U%!%$%kFb$N%G!<%?$r(BEmacs$B$NDL>o$N%G!<%?I=8=$X(B
$BJQ49!K$9$k$?$a$N%7%'%k%3%^%s%I$+4X?t!#(B

@c A shell command is represented as a string; Emacs runs the command as a
@c filter to perform the conversion.
$B%7%'%k%3%^%s%I$OJ8;zNs$GI=8=$7!"(B
Emacs$B$OJQ49$r9T$&$?$a$KEv3:%3%^%s%I$r%U%#%k%?$H$7$F<B9T$9$k!#(B

@c If @var{from-fn} is a function, it is called with two arguments, @var{begin}
@c and @var{end}, which specify the part of the buffer it should convert.
@c It should convert the text by editing it in place.  Since this can
@c change the length of the text, @var{from-fn} should return the modified
@c end position.
@var{from-fn}$B$,4X?t$G$"$k$H!"(B
$B%P%C%U%!$NJQ49$9$Y$-ItJ,$r;XDj$9$k(B@var{begin}$B$H(B@var{end}$B$N(B2$B$D$N0z?t$G(B
$B8F$P$l$k!#(B
$BEv3:4X?t$O$=$N>l$GJT=8$7$F%F%-%9%H$rJQ49$9$k$3$H!#(B
$B$3$l$K$h$j%F%-%9%H$ND9$5$,JQ$o$k2DG=@-$,$"$k$N$G!"(B
@var{from-fn}$B$OJQ99ItJ,$NKvHx0LCV$rJV$9$3$H!#(B

@c One responsibility of @var{from-fn} is to make sure that the beginning
@c of the file no longer matches @var{regexp}.  Otherwise it is likely to
@c get called again.
@var{from-fn}$B$N@UG$$N(B1$B$D$O!"(B
$B%U%!%$%k$N@hF,$,(B@var{regexp}$B$G;O$^$i$J$$$h$&$KJ]>Z$9$k$3$H$G$"$k!#(B
$B$5$b$J$$$H!":FEY8F$S=P$5$l$k2DG=@-$,$"$k!#(B

@item to-fn
@c A shell command or function to encode data in this format---that is, to
@c convert the usual Emacs data representation into this format.
$BEv3:=q<0$K%G!<%?$rId9f2=$9$k$?$a$N%7%'%k%3%^%s%I$+4X?t!#(B
$B$D$^$j!"(BEmacs$B$NDL>o$N%G!<%?I=8=$rEv3:=q<0$KJQ49$9$k!#(B

@c If @var{to-fn} is a string, it is a shell command; Emacs runs the
@c command as a filter to perform the conversion.
@var{to-fn}$B$,J8;zNs$G$"$k$H$=$l$O%7%'%k%3%^%s%I$G$"$j!"(B
Emacs$B$OJQ49$r9T$&$?$a$KEv3:%3%^%s%I$r%U%#%k%?$H$7$F<B9T$9$k!#(B

@c If @var{to-fn} is a function, it is called with two arguments, @var{begin}
@c and @var{end}, which specify the part of the buffer it should convert.
@c There are two ways it can do the conversion:
@var{to-fn}$B$,4X?t$G$"$k$H!"(B
$B%P%C%U%!$NJQ49$9$Y$-ItJ,$r;XDj$9$k(B@var{begin}$B$H(B@var{end}$B$N(B2$B$D$N0z?t$G(B
$B8F$P$l$k!#(B
$BJQ49$r9T$&$K$O(B2$B$D$NJ}K!$,$"$k!#(B

@itemize @bullet
@item
@c By editing the buffer in place.  In this case, @var{to-fn} should
@c return the end-position of the range of text, as modified.
$B$=$N>l$G%P%C%U%!$rJT=8$9$k!#(B
$B$3$N>l9g!"(B@var{to-fn}$B$OJQ99$7$?%F%-%9%HHO0O$N=*N;0LCV$rJV$9$3$H!#(B

@item
@c By returning a list of annotations.  This is a list of elements of the
@c form @code{(@var{position} . @var{string})}, where @var{position} is an
@c integer specifying the relative position in the text to be written, and
@c @var{string} is the annotation to add there.  The list must be sorted in
@c order of position when @var{to-fn} returns it.
$BCm5-$N%j%9%H$rJV$9!#(B
$B$3$N%j%9%H$O!"(B@code{(@var{position} . @var{string})}$B$N7A$NMWAG$+$i@.$j!"(B
@var{position}$B$O=q$-=P$9$Y$-%F%-%9%HFb$G$NAjBP0LCV$r;XDj$9$k@0?t!"(B
@var{string}$B$O$=$3$KDI2C$9$Y$-Cm5-$G$"$k!#(B
@var{to-fn}$B$,%j%9%H$rJV$9$H$-$K$O!"(B
$B%j%9%H$O(B@var{position}$B$N=g$K%=!<%H$7$F$"$k$3$H!#(B

@c When @code{write-region} actually writes the text from the buffer to the
@c file, it intermixes the specified annotations at the corresponding
@c positions.  All this takes place without modifying the buffer.
@code{write-region}$B$,%P%C%U%!$+$i%U%!%$%k$X<B:]$K=q$-=P$9$H$-!"(B
$B;XDj$5$l$?Cm5-$rBP1~$9$k0LCV$KKd$a9~$`!#(B
$B$3$l$i$9$Y$F$O!"%P%C%U%!$rJQ99$;$:$K9T$o$l$k!#(B
@end itemize

@item modify
@c A flag, @code{t} if the encoding function modifies the buffer, and
@c @code{nil} if it works by returning a list of annotations.
$B%U%i%0$G$"$j!"(B
$BId9f2=4X?t$,%P%C%U%!$rJQ99$9$k>l9g$K$O(B@code{t}$B!"(B
$BCm5-$N%j%9%H$rJV$9>l9g$K$O(B@code{nil}$B$G$"$k!#(B

@item mode
@c A mode function to call after visiting a file converted from this
@c format.
$BEv3:=q<0$+$iJQ49$5$l$?%U%!%$%k$rK,Ld8e$K8F$S=P$5$l$k%b!<%I4X?t!#(B
@end table

@c The function @code{insert-file-contents} automatically recognizes file
@c formats when it reads the specified file.  It checks the text of the
@c beginning of the file against the regular expressions of the format
@c definitions, and if it finds a match, it calls the decoding function for
@c that format.  Then it checks all the known formats over again.
@c It keeps checking them until none of them is applicable.
$B4X?t(B@code{insert-file-contents}$B$O!";XDj$5$l$?%U%!%$%k$rFI$_9~$`$H$-$K(B
$B%U%!%$%k=q<0$r<+F0E*$KG'<1$7$^$9!#(B
$B%U%!%$%k$N@hF,$N%F%-%9%H$r=q<0Dj5A$N@55,I=8=$KBP$7$F8!::$7$F!"(B
$B0lCW$,$_$D$+$l$PEv3:=q<0$NI|9f2=4X?t$r8F$S=P$7$^$9!#(B
$B$=$7$F!"4{CN$N=q<0$K$D$$$F:FEYD4$YD>$7$^$9!#(B
$BE,MQ$G$-$k=q<0$,$J$/$J$k$^$G8!::$7B3$1$^$9!#(B

@c Visiting a file, with @code{find-file-noselect} or the commands that use
@c it, performs conversion likewise (because it calls
@c @code{insert-file-contents}); it also calls the mode function for each
@c format that it decodes.  It stores a list of the format names in the
@c buffer-local variable @code{buffer-file-format}.
$B4X?t(B@code{find-file-noselect}$B$d$3$l$r;H$&%3%^%s%I$G%U%!%$%k$rK,Ld$9$k$H!"(B
$B!J(B@code{insert-file-contents}$B$r8F$S=P$9$N$G!KF1MM$KJQ49$r9T$$$^$9!#(B
$B$5$i$K!"$3$N4X?t$O!"I|9f$7$?3F=q<0$K$D$$$F%b!<%I4X?t$r8F$S=P$7$^$9!#(B
$B%P%C%U%!%m!<%+%k$JJQ?t(B@code{buffer-file-format}$B$K(B
$B=q<0L>$N%j%9%H$rJ]B8$7$^$9!#(B

@defvar buffer-file-format
@c This variable states the format of the visited file.  More precisely,
@c this is a list of the file format names that were decoded in the course
@c of visiting the current buffer's file.  It is always buffer-local in all
@c buffers.
$B$3$NJQ?t$O!"K,Ld$7$?%U%!%$%k$N=q<0$r5-=R$7$F$$$k!#(B
$B$h$j@53N$K$O!"%+%l%s%H%P%C%U%!$N%U%!%$%k$rK,Ld$9$k2aDx$G(B
$BI|9f$7$?%U%!%$%k=q<0L>$N%j%9%H$G$"$k!#(B
$B$3$NJQ?t$O!"$9$Y$F$N%P%C%U%!$K$*$$$F$D$M$K%P%C%U%!%m!<%+%k$G$"$k!#(B
@end defvar

@c When @code{write-region} writes data into a file, it first calls the
@c encoding functions for the formats listed in @code{buffer-file-format},
@c in the order of appearance in the list.
@code{write-region}$B$,%G!<%?$r%U%!%$%k$K=q$-=P$9$H$-$K$O!"$^$:!"(B
@code{buffer-file-format}$B$G;XDj$5$l$?=q<0$NId9f2=4X?t$r(B
$B%j%9%H$K8=$l$k=g$K8F$S=P$7$^$9!#(B

@c @deffn Command format-write-file file format
@deffn $B%3%^%s%I(B format-write-file file format
@c This command writes the current buffer contents into the file @var{file}
@c in format @var{format}, and makes that format the default for future
@c saves of the buffer.  The argument @var{format} is a list of format
@c names.
$B$3$N%3%^%s%I$O!"%+%l%s%H%P%C%U%!$NFbMF$r=q<0(B@var{format}$B$K$F(B
$B%U%!%$%k(B@var{file}$B$K=q$-=P$9!#(B
$B$5$i$K!"Ev3:=q<0$r%P%C%U%!$r>-MhJ]B8$9$k$H$-$N%G%U%)%k%H$H$9$k!#(B
$B0z?t(B@var{format}$B$O!"=q<0L>$N%j%9%H$G$"$k!#(B
@end deffn

@c @deffn Command format-find-file file format
@deffn $B%3%^%s%I(B format-find-file file format
@c This command finds the file @var{file}, converting it according to
@c format @var{format}.  It also makes @var{format} the default if the
@c buffer is saved later.
$B$3$N%3%^%s%I$O!"%U%!%$%k(B@var{file}$B$rC5$7!"(B
$B$=$l$r=q<0(B@var{format}$B$K=>$C$FJQ49$9$k!#(B
$B$5$i$K!"Ev3:=q<0$r%P%C%U%!$r$N$A$KJ]B8$9$k$H$-$N%G%U%)%k%H$H$9$k!#(B

@c The argument @var{format} is a list of format names.  If @var{format} is
@c @code{nil}, no conversion takes place.  Interactively, typing just
@c @key{RET} for @var{format} specifies @code{nil}.
$B0z?t(B@var{format}$B$O!"=q<0L>$N%j%9%H$G$"$k!#(B
@var{format}$B$,(B@code{nil}$B$G$"$k$H!"JQ49$r9T$o$J$$!#(B
$BBPOCE*$K8F$S=P$7$?>l9g!"(B
@var{format}$B$K(B@code{nil}$B$r;XDj$9$k$K$O(B@key{RET}$B$N$_$rBG$D!#(B
@end deffn

@c @deffn Command format-insert-file file format &optional beg end
@deffn $B%3%^%s%I(B format-insert-file file format &optional beg end
@c This command inserts the contents of file @var{file}, converting it
@c according to format @var{format}.  If @var{beg} and @var{end} are
@c non-@code{nil}, they specify which part of the file to read, as in
@c @code{insert-file-contents} (@pxref{Reading from Files}).
$B$3$N%3%^%s%I$O!"%U%!%$%k(B@var{file}$B$NFbMF$r=q<0(B@var{format}$B$K=>$C$F(B
$BJQ49$7$FA^F~$9$k!#(B
@var{beg}$B$H(B@var{end}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B$=$l$i$O!"(B@code{insert-file-contents}$B!J(B@pxref{Reading from Files}$B!K$HF1MM$K!"(B
$BFI$_9~$`$Y$-%U%!%$%k$NItJ,$r;XDj$9$k!#(B

@c The return value is like what @code{insert-file-contents} returns: a
@c list of the absolute file name and the length of the data inserted
@c (after conversion).
$BLa$jCM$O!"(B@code{insert-file-contents}$B$,JV$9CM$K;w$F$*$j!"(B
$B@dBP%U%!%$%kL>$HA^F~%G!<%?$N!JJQ498e$N!KD9$5$N%j%9%H$G$"$k!#(B

@c The argument @var{format} is a list of format names.  If @var{format} is
@c @code{nil}, no conversion takes place.  Interactively, typing just
@c @key{RET} for @var{format} specifies @code{nil}.
$B0z?t(B@var{format}$B$O!"=q<0L>$N%j%9%H$G$"$k!#(B
@var{format}$B$,(B@code{nil}$B$G$"$k$H!"JQ49$r9T$o$J$$!#(B
$BBPOCE*$K8F$S=P$7$?>l9g!"(B
@var{format}$B$K(B@code{nil}$B$r;XDj$9$k$K$O(B@key{RET}$B$N$_$rBG$D!#(B
@end deffn

@defvar auto-save-file-format
@c This variable specifies the format to use for auto-saving.  Its value is
@c a list of format names, just like the value of
@c @code{buffer-file-format}; however, it is used instead of
@c @code{buffer-file-format} for writing auto-save files.  This variable is
@c always buffer-local in all buffers.
$B$3$NJQ?t$O!"<+F0J]B8$KBP$7$F;HMQ$9$k=q<0$r;XDj$9$k!#(B
$B$=$NCM$O!"(B@code{buffer-file-format}$B$NCM$N$h$&$K!"=q<0L>$N%j%9%H$G$"$k$,!"(B
@code{buffer-file-format}$B$N$+$o$j$K(B
$B<+F0J]B8%U%!%$%k$r=q$/$?$a$K;H$o$l$k!#(B
$B$3$NJQ?t$O!"$9$Y$F$N%P%C%U%!$K$*$$$F$D$M$K%P%C%U%!%m!<%+%k$G$"$k!#(B
@end defvar