files.texi 79 KB
Newer Older
Richard M. Stallman's avatar
Richard M. Stallman committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 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
@chapter Files

  In Emacs, you can find, create, view, save, and otherwise work with
files and file directories.  This chapter describes most of the
file-related functions of Emacs Lisp, but a few others are described in
@ref{Buffers}, and those related to backups and auto-saving are
described in @ref{Backups and Auto-Saving}.

16 17 18 19 20 21 22
  Many of the file functions take one or more arguments that are file
names.  A file name is actually a string.  Most of these functions
expand file name arguments using @code{expand-file-name}, so that
@file{~} is handled correctly, as are relative file names (including
@samp{../}).  These functions don't recognize environment variable
substitutions such as @samp{$HOME}.  @xref{File Name Expansion}.

Richard M. Stallman's avatar
Richard M. Stallman committed
23 24 25 26 27 28 29 30 31 32 33 34 35 36
@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 File Attributes:: 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.
Karl Heuer's avatar
Karl Heuer committed
37
* Format Conversion::        Conversion to and from various file formats.
38
* Files and MS-DOS::         Distinguishing text and binary files on MS-DOS.
Richard M. Stallman's avatar
Richard M. Stallman committed
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
@end menu

@node Visiting Files
@section Visiting Files
@cindex finding files
@cindex visiting files

  Visiting a file means reading a file into a buffer.  Once this is
done, we say that the buffer is @dfn{visiting} that file, and call the
file ``the visited file'' of the buffer.

  A file and a buffer are two different things.  A file is information
recorded permanently in the computer (unless you delete it).  A buffer,
on the other hand, is information inside of Emacs that will vanish at
the end of the editing session (or when you kill the buffer).  Usually,
a buffer contains information that you have copied from a file; then we
say the buffer is visiting that file.  The copy in the buffer is what
you modify with editing commands.  Such changes to the buffer do not
change the file; therefore, to make the changes permanent, you must
@dfn{save} the buffer, which means copying the altered buffer contents
back into the file.

  In spite of the distinction between files and buffers, people often
refer to a file when they mean a buffer and vice-versa.  Indeed, we say,
63
``I am editing a file,'' rather than, ``I am editing a buffer that I
Richard M. Stallman's avatar
Richard M. Stallman committed
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
will soon save as a file of the same name.''  Humans do not usually need
to make the distinction explicit.  When dealing with a computer program,
however, it is good to keep the distinction in mind.

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

@node Visiting Functions
@subsection Functions for Visiting Files

  This section describes the functions normally used to visit files.
For historical reasons, these functions have names starting with
@samp{find-} rather than @samp{visit-}.  @xref{Buffer File Name}, for
functions and variables that access the visited file name of a buffer or
that find an existing buffer by its visited file name.

Karl Heuer's avatar
Karl Heuer committed
82 83 84 85 86
  In a Lisp program, if you want to look at the contents of a file but
not alter it, the fastest way is to use @code{insert-file-contents} in a
temporary buffer.  Visiting the file is not necessary and takes longer.
@xref{Reading from Files}.

Richard M. Stallman's avatar
Richard M. Stallman committed
87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
@deffn Command find-file filename
This command selects a buffer visiting the file @var{filename},
using an existing buffer if there is one, and otherwise creating a 
new buffer and reading the file into it.  It also returns that buffer.

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

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

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

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

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

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

If @code{find-file-noselect} needs to create a buffer, and there is no
file named @var{filename}, it displays the message @samp{New file} in
the echo area, and leaves the buffer empty.

The @code{find-file-noselect} function calls @code{after-find-file}
after reading the file (@pxref{Subroutines of Visiting}).  That function
sets the buffer major mode, parses local variables, warns the user if
there exists an auto-save file more recent than the file just visited,
and finishes by running the functions in @code{find-file-hooks}.

The @code{find-file-noselect} function returns the buffer that is
visiting the file @var{filename}.

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

@deffn Command find-file-other-window filename
This command selects a buffer visiting the file @var{filename}, but
does so in a window other than the selected window.  It may use another
existing window or split a window; see @ref{Displaying Buffers}.

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

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

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

@deffn Command view-file filename
Karl Heuer's avatar
Karl Heuer committed
159 160 161 162 163
This command visits @var{filename} in View mode, and displays it in a
recursive edit, returning to the previous buffer when done.  View mode
is a mode that allows you to skim rapidly through the file but does not
let you modify it.  Entering View mode runs the normal hook
@code{view-mode-hook}.  @xref{Hooks}.
Richard M. Stallman's avatar
Richard M. Stallman committed
164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206

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

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

This variable works just like a normal hook, but we think that renaming
it would not be advisable.
@end defvar

@defvar find-file-not-found-hooks
The value of this variable is a list of functions to be called when
@code{find-file} or @code{find-file-noselect} is passed a nonexistent
file name.  @code{find-file-noselect} calls these functions as soon as
it detects a nonexistent file.  It calls them in the order of the list,
until one of them returns non-@code{nil}.  @code{buffer-file-name} is
already set up.

This is not a normal hook because the values of the functions are
used and they may not all be called.
@end defvar

@node Subroutines of Visiting
@comment  node-name,  next,  previous,  up
@subsection Subroutines of Visiting

  The @code{find-file-noselect} function uses the
@code{create-file-buffer} and @code{after-find-file} functions as
subroutines.  Sometimes it is useful to call them directly.

@defun create-file-buffer filename
This function creates a suitably named buffer for visiting
@var{filename}, and returns it.  It uses @var{filename} (sans directory)
as the name if that name is free; otherwise, it appends a string such as
@samp{<2>} to get an unused name.  See also @ref{Creating Buffers}.

@strong{Please note:} @code{create-file-buffer} does @emph{not}
associate the new buffer with a file and does not select the buffer.
Karl Heuer's avatar
Karl Heuer committed
207
It also does not use the default major mode.
Richard M. Stallman's avatar
Richard M. Stallman committed
208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263

@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

This function is used by @code{find-file-noselect}.
It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
@end defun

@defun after-find-file &optional error warn
This function sets the buffer major mode, and parses local variables
(@pxref{Auto Major Mode}).  It is called by @code{find-file-noselect}
and by the default revert function (@pxref{Reverting}).

@cindex new file message
@cindex file open error
If reading the file got an error because the file does not exist, but
its directory does exist, the caller should pass a non-@code{nil} value
for @var{error}.  In that case, @code{after-find-file} issues a warning:
@samp{(New File)}.  For more serious errors, the caller should usually not
call @code{after-find-file}.

If @var{warn} is non-@code{nil}, then this function issues a warning
if an auto-save file exists and is more recent than the visited file.

The last thing @code{after-find-file} does is call all the functions
in @code{find-file-hooks}.
@end defun

@node Saving Buffers
@section Saving Buffers

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

@deffn Command save-buffer &optional backup-option
This function saves the contents of the current buffer in its visited
file if the buffer has been modified since it was last visited or saved.
Otherwise it does nothing.

@code{save-buffer} is responsible for making backup files.  Normally,
@var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
264 265 266
file only if this is the first save since visiting the file.  Other
values for @var{backup-option} request the making of backup files in
other circumstances:
Richard M. Stallman's avatar
Richard M. Stallman committed
267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310

@itemize @bullet
@item
With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
@code{save-buffer} function marks this version of the file to be
backed up when the buffer is next saved.

@item
With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
@code{save-buffer} function unconditionally backs up the previous
version of the file before saving it.
@end itemize
@end deffn

@deffn Command save-some-buffers &optional save-silently-p exiting
This command saves some modified file-visiting buffers.  Normally it
asks the user about each buffer.  But if @var{save-silently-p} is
non-@code{nil}, it saves all the file-visiting buffers without querying
the user.

The optional @var{exiting} argument, if non-@code{nil}, requests this
function to offer also to save certain other buffers that are not
visiting files.  These are buffers that have a non-@code{nil} local
value of @code{buffer-offer-save}.  (A user who says yes to saving one
of these is asked to specify a file name to use.)  The
@code{save-buffers-kill-emacs} function passes a non-@code{nil} value
for this argument.
@end deffn

@defvar buffer-offer-save
When this variable is non-@code{nil} in a buffer, Emacs offers to save
the buffer on exit even if the buffer is not visiting a file.  The
variable is automatically local in all buffers.  Normally, Mail mode
(used for editing outgoing mail) sets this to @code{t}.
@end defvar

@deffn Command write-file filename
This function writes the current buffer into file @var{filename}, makes
the buffer visit that file, and marks it not modified.  Then it renames
the buffer based on @var{filename}, appending a string like @samp{<2>}
if necessary to make a unique buffer name.  It does most of this work by
calling @code{set-visited-file-name} and @code{save-buffer}.
@end deffn

311 312 313 314
  Saving a buffer runs several hooks.  It also performs format
conversion (@pxref{Format Conversion}), and may save text properties in
``annotations'' (@pxref{Saving Properties}).

Richard M. Stallman's avatar
Richard M. Stallman committed
315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353
@defvar write-file-hooks
The value of this variable is a list of functions to be called before
writing out a buffer to its visited file.  If one of them returns
non-@code{nil}, the file is considered already written and the rest of
the functions are not called, nor is the usual code for writing the file
executed.

If a function in @code{write-file-hooks} returns non-@code{nil}, it
is responsible for making a backup file (if that is appropriate).
To do so, execute the following code:

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

You might wish to save the file modes value returned by
@code{backup-buffer} and use that to set the mode bits of the file that
you write.  This is what @code{save-buffer} normally does.

Even though this is not a normal hook, you can use @code{add-hook} and
@code{remove-hook} to manipulate the list.  @xref{Hooks}.
@end defvar

@c Emacs 19 feature
@defvar local-write-file-hooks
This works just like @code{write-file-hooks}, but it is intended
to be made local to particular buffers.  It's not a good idea to make
@code{write-file-hooks} local to a buffer---use this variable instead.

The variable is marked as a permanent local, so that changing the major
mode does not alter a buffer-local value.  This is convenient for
packages that read ``file'' contents in special ways, and set up hooks
to save the data in a corresponding way.
@end defvar

@c Emacs 19 feature
@defvar write-contents-hooks
This works just like @code{write-file-hooks}, but it is intended for
hooks that pertain to the contents of the file, as opposed to hooks that
Richard M. Stallman's avatar
Richard M. Stallman committed
354
pertain to where the file came from.  Such hooks are usually set up by
355 356 357 358 359 360 361
major modes, as buffer-local bindings for this variable.

This variable automatically becomes buffer-local whenever it is set;
switching to a new major mode always resets this variable.  When you use
@code{add-hooks} to add an element to this hook, you should @emph{not}
specify a non-@code{nil} @var{local} argument, since this variable is
used @emph{only} locally.
Richard M. Stallman's avatar
Richard M. Stallman committed
362 363 364 365 366 367 368 369 370 371 372 373 374 375 376
@end defvar

@c Emacs 19 feature
@defvar after-save-hook
This normal hook runs after a buffer has been saved in its visited file.
@end defvar

@defvar file-precious-flag
If this variable is non-@code{nil}, then @code{save-buffer} protects
against I/O errors while saving by writing the new file to a temporary
name instead of the name it is supposed to have, and then renaming it to
the intended name after it is clear there are no errors.  This procedure
prevents problems such as a lack of disk space from resulting in an
invalid file.

Melissa Weisshaus's avatar
Melissa Weisshaus committed
377 378 379
As a side effect, backups are necessarily made by copying.  @xref{Rename
or Copy}.  Yet, at the same time, saving a precious file always breaks
all hard links between the file you save and other file names.
Richard M. Stallman's avatar
Richard M. Stallman committed
380

Karl Heuer's avatar
Karl Heuer committed
381 382
Some modes set this variable non-@code{nil} locally in particular
buffers.
Richard M. Stallman's avatar
Richard M. Stallman committed
383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398
@end defvar

@defopt require-final-newline
This variable determines whether files may be written out that do
@emph{not} end with a newline.  If the value of the variable is
@code{t}, then @code{save-buffer} silently adds a newline at the end of
the file whenever the buffer being saved does not already end in one.
If the value of the variable is non-@code{nil}, but not @code{t}, then
@code{save-buffer} asks the user whether to add a newline each time the
case arises.

If the value of the variable is @code{nil}, then @code{save-buffer}
doesn't add newlines at all.  @code{nil} is the default value, but a few
major modes set it to @code{t} in particular buffers.
@end defopt

399 400 401 402 403 404 405 406 407 408 409
@deffn Command set-visited-file-name filename &optional no-query
This function changes the visited file name of the current buffer to
@var{filename}.  It also renames the buffer based on @var{filename},
appending a string like @samp{<2>} if necessary to make a unique buffer
name.  It marks the buffer as @emph{modified},a since the contents do not
(as far as Emacs knows) match the actual file's contents.

If the specified file already exists, @code{set-visited-file-name}
asks for confirmation unless @var{no-query} is non-@code{nil}.
@end deffn

Richard M. Stallman's avatar
Richard M. Stallman committed
410 411 412 413 414 415 416 417 418 419
@node Reading from Files
@comment  node-name,  next,  previous,  up
@section Reading from Files

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

@defun insert-file-contents filename &optional visit beg end replace
This function inserts the contents of file @var{filename} into the
Melissa Weisshaus's avatar
Melissa Weisshaus committed
420
current buffer after point.  It returns a list of the absolute file name
Richard M. Stallman's avatar
Richard M. Stallman committed
421 422 423
and the length of the data inserted.  An error is signaled if
@var{filename} is not the name of a file that can be read.

Karl Heuer's avatar
Karl Heuer committed
424 425 426 427 428
The function @code{insert-file-contents} checks the file contents
against the defined file formats, and converts the file contents if
appropriate.  @xref{Format Conversion}.  It also calls the functions in
the list @code{after-insert-file-functions}; see @ref{Saving
Properties}.
Richard M. Stallman's avatar
Richard M. Stallman committed
429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504

If @var{visit} is non-@code{nil}, this function additionally marks the
buffer as unmodified and sets up various fields in the buffer so that it
is visiting the file @var{filename}: these include the buffer's visited
file name and its last save file modtime.  This feature is used by
@code{find-file-noselect} and you probably should not use it yourself.

If @var{beg} and @var{end} are non-@code{nil}, they should be integers
specifying the portion of the file to insert.  In this case, @var{visit}
must be @code{nil}.  For example,

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

@noindent
inserts the first 500 characters of a file.

If the argument @var{replace} is non-@code{nil}, it means to replace the
contents of the buffer (actually, just the accessible portion) with the
contents of the file.  This is better than simply deleting the buffer
contents and inserting the whole file, because (1) it preserves some
marker positions and (2) it puts less data in the undo list.
@end defun

If you want to pass a file name to another process so that another
program can read the file, use the function @code{file-local-copy}; see
@ref{Magic File Names}.

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

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

@deffn Command append-to-file start end filename
This function appends the contents of the region delimited by
@var{start} and @var{end} in the current buffer to the end of file
@var{filename}.  If that file does not exist, it is created.  This
function returns @code{nil}.

An error is signaled if @var{filename} specifies a nonwritable file,
or a nonexistent file in a directory where files cannot be created.
@end deffn

@deffn Command write-region start end filename &optional append visit
This function writes the region delimited by @var{start} and @var{end}
in the current buffer into the file specified by @var{filename}.

@c Emacs 19 feature
If @var{start} is a string, then @code{write-region} writes or appends
that string, rather than text from the buffer.

If @var{append} is non-@code{nil}, then the specified text is appended
to the existing file contents (if any).

If @var{visit} is @code{t}, then Emacs establishes an association
between the buffer and the file: the buffer is then visiting that file.
It also sets the last file modification time for the current buffer to
@var{filename}'s modtime, and marks the buffer as not modified.  This
feature is used by @code{save-buffer}, but you probably should not use
it yourself.

@c Emacs 19 feature
If @var{visit} is a string, it specifies the file name to visit.  This
way, you can write the data to one file (@var{filename}) while recording
the buffer as visiting another file (@var{visit}).  The argument
@var{visit} is used in the echo area message and also for file locking;
@var{visit} is stored in @code{buffer-file-name}.  This feature is used
to implement @code{file-precious-flag}; don't use it yourself unless you
really know what you're doing.

Karl Heuer's avatar
Karl Heuer committed
505 506 507 508
The function @code{write-region} converts the data which it writes to
the appropriate file formats specified by @code{buffer-file-format}.
@xref{Format Conversion}.  It also calls the functions in the list
@code{write-region-annotate-functions}; see @ref{Saving Properties}.
Richard M. Stallman's avatar
Richard M. Stallman committed
509 510 511 512 513

Normally, @code{write-region} displays a message @samp{Wrote file
@var{filename}} in the echo area.  If @var{visit} is neither @code{t}
nor @code{nil} nor a string, then this message is inhibited.  This
feature is useful for programs that use files for internal purposes,
514
files that the user does not need to know about.
Richard M. Stallman's avatar
Richard M. Stallman committed
515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564
@end deffn

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

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

  File locks do not work properly when multiple machines can share
file systems, such as with NFS.  Perhaps a better file locking system
will be implemented in the future.  When file locks do not work, it is
possible for two users to make changes simultaneously, but Emacs can
still warn the user who saves second.  Also, the detection of
modification of a buffer visiting a file changed on disk catches some
cases of simultaneous editing; see @ref{Modification Time}.

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

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

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

@defun unlock-buffer
This function unlocks the file being visited in the current buffer,
if the buffer is modified.  If the buffer is not modified, then
the file should not be locked, so this function does nothing.  It also
does nothing if the current buffer is not visiting a file.
@end defun

@defun ask-user-about-lock file other-user
This function is called when the user tries to modify @var{file}, but it
565
is locked by another user named @var{other-user}.  The value it returns
Richard M. Stallman's avatar
Richard M. Stallman committed
566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601
determines what happens next:

@itemize @bullet
@item
A value of @code{t} says to grab the lock on the file.  Then
this user may edit the file and @var{other-user} loses the lock.

@item
A value of @code{nil} says to ignore the lock and let this
user edit the file anyway.

@item
@kindex file-locked
This function may instead signal a @code{file-locked} error, in which
case the change that the user was about to make does not take place.

The error message for this error looks like this:

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

@noindent
where @code{file} is the name of the file and @var{other-user} is the
name of the user who has locked the file.
@end itemize

  The default definition of this function asks the user to choose what
to do.  If you wish, you can replace the @code{ask-user-about-lock}
function with your own version that decides in another way.  The code
for its usual definition is in @file{userlock.el}.
@end defun

@node Information about Files
@section Information about Files

602 603 604 605 606
  The functions described in this section all operate on strings that
designate file names.  All the functions have names that begin with the
word @samp{file}.  These functions all return information about actual
files or directories, so their arguments must all exist as actual files
or directories unless otherwise noted.
Richard M. Stallman's avatar
Richard M. Stallman committed
607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664

@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
@subsection Testing Accessibility
@cindex accessibility of a file
@cindex file accessibility

  These functions test for permission to access a file in specific ways.

@defun file-exists-p filename
This function returns @code{t} if a file named @var{filename} appears
to exist.  This does not mean you can necessarily read the file, only
that you can find out its attributes.  (On Unix, this is true if the
file exists and you have execute permission on the containing
directories, regardless of the protection of the file itself.)

If the file does not exist, or if fascist access control policies
prevent you from finding the attributes of the file, this function
returns @code{nil}.
@end defun

@defun file-readable-p filename
This function returns @code{t} if a file named @var{filename} exists
and you can read it.  It returns @code{nil} otherwise.

@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
This function returns @code{t} if a file named @var{filename} exists and
you can execute it.  It returns @code{nil} otherwise.  If the file is a
directory, execute permission means you can check the existence and
attributes of files inside the directory, and open those files if their
modes permit.
@end defun

@defun file-writable-p filename
665 666 667 668 669
This function returns @code{t} if the file @var{filename} can be written
or created by you, and @code{nil} otherwise.  A file is writable if the
file exists and you can write it.  It is creatable if it does not exist,
but the specified directory does exist and you can write in that
directory.
Richard M. Stallman's avatar
Richard M. Stallman committed
670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693

In the third example below, @file{foo} is not writable because the
parent directory does not exist, even though the user could create such
a directory.

@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
This function returns @code{t} if you have permission to open existing
694 695 696 697
files in the directory whose name as a file is @var{dirname}; otherwise
(or if there is no such directory), it returns @code{nil}.  The value
of @var{dirname} may be either a directory name or the file name of a
directory.
Richard M. Stallman's avatar
Richard M. Stallman committed
698 699 700 701 702 703 704 705 706 707 708 709 710

Example: after the following,

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

@noindent
we can deduce that any attempt to read a file in @file{/foo/} will
give an error.
@end defun

Karl Heuer's avatar
Karl Heuer committed
711 712 713 714 715
@defun file-ownership-preserved-p filename
This function returns @code{t} if deleting the file @var{filename} and
then creating it anew would keep the file's owner unchanged.
@end defun

Richard M. Stallman's avatar
Richard M. Stallman committed
716 717 718
@defun file-newer-than-file-p filename1 filename2
@cindex file age
@cindex file modification time
719
This function returns @code{t} if the file @var{filename1} is
Richard M. Stallman's avatar
Richard M. Stallman committed
720 721 722 723
newer than file @var{filename2}.  If @var{filename1} does not
exist, it returns @code{nil}.  If @var{filename2} does not exist,
it returns @code{t}.

724 725 726
In the following example, assume that the file @file{aug-19} was written
on the 19th, @file{aug-20} was written on the 20th, and the file
@file{no-file} doesn't exist at all.
Richard M. Stallman's avatar
Richard M. Stallman committed
727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754

@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

You can use @code{file-attributes} to get a file's last modification
time as a list of two numbers.  @xref{File Attributes}.
@end defun

@node Kinds of Files
@comment  node-name,  next,  previous,  up
@subsection Distinguishing Kinds of Files

Karl Heuer's avatar
Karl Heuer committed
755 756
  This section describes how to distinguish various kinds of files, such
as directories, symbolic links, and ordinary files.
Richard M. Stallman's avatar
Richard M. Stallman committed
757 758 759 760 761

@defun file-symlink-p filename
@cindex file symbolic links
If the file @var{filename} is a symbolic link, the @code{file-symlink-p}
function returns the file name to which it is linked.  This may be the
762 763
name of a text file, a directory, or even another symbolic link, or it
may be a nonexistent file name.
Richard M. Stallman's avatar
Richard M. Stallman committed
764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818

If the file @var{filename} is not a symbolic link (or there is no such file),
@code{file-symlink-p} returns @code{nil}.  

@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
This function returns @code{t} if @var{filename} is the name of an
existing directory, @code{nil} otherwise.

@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

Karl Heuer's avatar
Karl Heuer committed
819 820 821 822 823 824
@defun file-regular-p filename
This function returns @code{t} if the file @var{filename} exists and is
a regular file (not a directory, symbolic link, named pipe, terminal, or
other I/O device).
@end defun

Richard M. Stallman's avatar
Richard M. Stallman committed
825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860
@node Truenames
@subsection Truenames
@cindex truename (of file)

@c Emacs 19 features
  The @dfn{truename} of a file is the name that you get by following
symbolic links until none remain, then expanding to get rid of @samp{.}
and @samp{..} as components.  Strictly speaking, a file need not have a
unique truename; the number of distinct truenames a file has is equal to
the number of hard links to the file.  However, truenames are useful
because they eliminate symbolic links as a cause of name variation.

@defun file-truename filename
The function @code{file-truename} returns the true name of the file
@var{filename}.  This is the name that you get by following symbolic
links until none remain.  The argument must be an absolute file name.
@end defun

  @xref{Buffer File Name}, for related information.

@node File Attributes
@comment  node-name,  next,  previous,  up
@subsection Other Information about Files

  This section describes the functions for getting detailed information
about a file, other than its contents.  This information includes the
mode bits that control access permission, the owner and group numbers,
the number of names, the inode number, the size, and the times of access
and modification.

@defun file-modes filename
@cindex permission
@cindex file attributes
This function returns the mode bits of @var{filename}, as an integer.
The mode bits are also called the file permissions, and they specify
access control in the usual Unix fashion.  If the low-order bit is 1,
861
then the file is executable by all users, if the second-lowest-order bit
Richard M. Stallman's avatar
Richard M. Stallman committed
862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958
is 1, then the file is writable by all users, etc.

The highest value returnable is 4095 (7777 octal), meaning that
everyone has read, write, and execute permission, that the @sc{suid} bit
is set for both others and group, and that the sticky bit is set.

@example
@group
(file-modes "~/junk/diffs")
     @result{} 492               ; @r{Decimal integer.}
@end group
@group
(format "%o" 492)
     @result{} "754"             ; @r{Convert to octal.}
@end group

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

@group
(format "%o" 438)
     @result{} "666"             ; @r{Convert to octal.}
@end group

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

@defun file-nlinks filename
This functions returns the number of names (i.e., hard links) that
file @var{filename} has.  If the file does not exist, then this function
returns @code{nil}.  Note that symbolic links have no effect on this
function, because they are not considered to be names of the files they
link to.

@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
This function returns a list of attributes of file @var{filename}.  If
the specified file cannot be opened, it returns @code{nil}.

The elements of the list, in order, are:

@enumerate 0
@item
@code{t} for a directory, a string for a symbolic link (the name
linked to), or @code{nil} for a text file.

@c Wordy so as to prevent an overfull hbox.  --rjc 15mar92
@item
The number of names the file has.  Alternate names, also known as hard
links, can be created by using the @code{add-name-to-file} function
(@pxref{Changing File Attributes}).

@item
The file's @sc{uid}.

@item
The file's @sc{gid}.

@item
The time of last access, as a list of two integers.
The first integer has the high-order 16 bits of time,
the second has the low 16 bits.  (This is similar to the
value of @code{current-time}; see @ref{Time of Day}.)

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

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

@item
The size of the file in bytes.

@item
959
The file's modes, as a string of ten letters or dashes,
Richard M. Stallman's avatar
Richard M. Stallman committed
960 961 962 963 964 965 966
as in @samp{ls -l}.

@item
@code{t} if the file's @sc{gid} would change if file were
deleted and recreated; @code{nil} otherwise.

@item
967 968 969 970
The file's inode number.  If possible, this is an integer.  If the inode
number is too large to be represented as an integer in Emacs Lisp, then
the value has the form @code{(@var{high} . @var{low})}, where @var{low}
holds the low 16 bits.
Richard M. Stallman's avatar
Richard M. Stallman committed
971 972 973

@item
The file system number of the file system that the file is in.  This
974 975 976
element and the file's inode number together give enough information to
distinguish any two files on the system---no two files can have the same
values for both of these numbers.
Richard M. Stallman's avatar
Richard M. Stallman committed
977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016
@end enumerate

For example, here are the file attributes for @file{files.texi}:

@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
and here is how the result is interpreted:

@table @code
@item nil
is neither a directory nor a symbolic link.

@item 1
has only one name (the name @file{files.texi} in the current default
directory).

@item 2235
is owned by the user with @sc{uid} 2235.

@item 75
is in the group with @sc{gid} 75.

@item (8489 20284)
Richard M. Stallman's avatar
Richard M. Stallman committed
1017
was last accessed on Aug 19 00:09.
Richard M. Stallman's avatar
Richard M. Stallman committed
1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086

@item (8489 20284)
was last modified on Aug 19 00:09.

@item (8489 20285)
last had its inode changed on Aug 19 00:09.

@item 14906
is 14906 characters long.

@item "-rw-rw-rw-"
has a mode of read and write access for the owner, group, and world.

@item nil
would retain the same @sc{gid} if it were recreated.

@item 129500
has an inode number of 129500.
@item -32252
is on file system number -32252.
@end table
@end defun

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

  The functions in this section rename, copy, delete, link, and set the
modes of files.

  In the functions that have an argument @var{newname}, if a file by the
name of @var{newname} already exists, the actions taken depend on the
value of the argument @var{ok-if-already-exists}:

@itemize @bullet
@item
Signal a @code{file-already-exists} error if
@var{ok-if-already-exists} is @code{nil}.

@item
Request confirmation if @var{ok-if-already-exists} is a number.

@item
Replace the old file without confirmation if @var{ok-if-already-exists}
is any other value.
@end itemize

@defun add-name-to-file oldname newname &optional ok-if-already-exists
@cindex file with multiple names
@cindex file hard link
This function gives the file named @var{oldname} the additional name
@var{newname}.  This means that @var{newname} becomes a new ``hard
link'' to @var{oldname}.

In the first part of the following example, we list two files,
@file{foo} and @file{foo3}.

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

1087 1088 1089
Now we create a hard link, by calling @code{add-name-to-file}, then list
the files again.  This shows two names for one file, @file{foo} and
@file{foo2}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182

@example
@group
(add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
     @result{} nil
@end group

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

@c !!! Check whether this set of examples is consistent.  --rjc 15mar92
  Finally, we evaluate the following:

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

@noindent
and list the files again.  Now there are three names
for one file: @file{foo}, @file{foo2}, and @file{foo3}.  The old
contents of @file{foo3} are lost.

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

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

  This function is meaningless on VMS, where multiple names for one file
are not allowed.

  See also @code{file-nlinks} in @ref{File Attributes}.
@end defun

@deffn Command rename-file filename newname &optional ok-if-already-exists
This command renames the file @var{filename} as @var{newname}.

If @var{filename} has additional names aside from @var{filename}, it
continues to have those names.  In fact, adding the name @var{newname}
with @code{add-name-to-file} and then deleting @var{filename} has the
same effect as renaming, aside from momentary intermediate states.

In an interactive call, this function prompts for @var{filename} and
@var{newname} in the minibuffer; also, it requests confirmation if
@var{newname} already exists.
@end deffn

@deffn Command copy-file oldname newname &optional ok-if-exists time
This command copies the file @var{oldname} to @var{newname}.  An
error is signaled if @var{oldname} does not exist.

If @var{time} is non-@code{nil}, then this functions gives the new
file the same last-modified time that the old one has.  (This works on
only some operating systems.)

In an interactive call, this function prompts for @var{filename} and
@var{newname} in the minibuffer; also, it requests confirmation if
@var{newname} already exists.
@end deffn

@deffn Command delete-file filename
@pindex rm
This command deletes the file @var{filename}, like the shell command
@samp{rm @var{filename}}.  If the file has multiple names, it continues
to exist under the other names.

A suitable kind of @code{file-error} error is signaled if the file
does not exist, or is not deletable.  (On Unix, a file is deletable if
its directory is writable.)

See also @code{delete-directory} in @ref{Create/Delete Dirs}.
@end deffn

@deffn Command make-symbolic-link filename newname  &optional ok-if-exists
@pindex ln
@kindex file-already-exists
This command makes a symbolic link to @var{filename}, named
@var{newname}.  This is like the shell command @samp{ln -s
@var{filename} @var{newname}}.

1183 1184 1185
In an interactive call, this function prompts for @var{filename} and
@var{newname} in the minibuffer; also, it requests confirmation if
@var{newname} already exists.
Richard M. Stallman's avatar
Richard M. Stallman committed
1186 1187 1188 1189 1190 1191 1192 1193 1194
@end deffn

@defun define-logical-name varname string
This function defines the logical name @var{name} to have the value
@var{string}.  It is available only on VMS.
@end defun

@defun set-file-modes filename mode
This function sets mode bits of @var{filename} to @var{mode} (which must
1195
be an integer).  Only the low 12 bits of @var{mode} are used.
Richard M. Stallman's avatar
Richard M. Stallman committed
1196 1197 1198 1199 1200 1201 1202 1203 1204
@end defun

@c Emacs 19 feature
@defun set-default-file-modes mode
This function sets the default file protection for new files created by
Emacs and its subprocesses.  Every file created with Emacs initially has
this protection.  On Unix, the default protection is the bitwise
complement of the ``umask'' value.

1205
The argument @var{mode} must be an integer.  Only the low 9 bits of
Richard M. Stallman's avatar
Richard M. Stallman committed
1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216
@var{mode} are used.

Saving a modified version of an existing file does not count as creating
the file; it does not change the file's mode, and does not use the
default file protection.
@end defun

@defun default-file-modes
This function returns the current default protection value.
@end defun

1217 1218 1219 1220 1221 1222 1223
@cindex MS-DOS and file modes
@cindex file modes and MS-DOS
  On MS-DOS, there is no such thing as an ``executable'' file mode bit.
So Emacs considers a file executable if its name ends in @samp{.com},
@samp{.bat} or @samp{.exe}.  This is reflected in the values returned
by @code{file-modes} and @code{file-attributes}.

Richard M. Stallman's avatar
Richard M. Stallman committed
1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240
@node File Names
@section File Names
@cindex file names

  Files are generally referred to by their names, in Emacs as elsewhere.
File names in Emacs are represented as strings.  The functions that
operate on a file all expect a file name argument.

  In addition to operating on files themselves, Emacs Lisp programs
often need to operate on the names; i.e., to take them apart and to use
part of a name to construct related file names.  This section describes
how to manipulate file names.

  The functions in this section do not actually access files, so they
can operate on file names that do not refer to an existing file or
directory.

1241
  On VMS, all these functions understand both VMS file-name syntax and
Richard M. Stallman's avatar
Richard M. Stallman committed
1242 1243
Unix syntax.  This is so that all the standard Lisp libraries can
specify file names in Unix syntax and work properly on VMS without
1244
change.  On MS-DOS, these functions understand MS-DOS file-name syntax
1245
as well as Unix syntax.
Richard M. Stallman's avatar
Richard M. Stallman committed
1246 1247 1248 1249 1250 1251 1252 1253 1254

@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.
1255 1256
* Standard File Names::   If your package uses a fixed file name,
                            how to handle various operating systems simply.
Richard M. Stallman's avatar
Richard M. Stallman committed
1257 1258 1259 1260 1261 1262 1263 1264 1265
@end menu

@node File Name Components
@subsection File Name Components
@cindex directory part (of file name)
@cindex nondirectory part (of file name)
@cindex version number (in file name)

  The operating system groups files into directories.  To specify a
1266 1267 1268 1269 1270
file, you must specify the directory and the file's name within that
directory.  Therefore, Emacs considers a file name as having two main
parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
(or @dfn{file name within the directory}).  Either part may be empty.
Concatenating these two parts reproduces the original file name.
Richard M. Stallman's avatar
Richard M. Stallman committed
1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350

  On Unix, the directory part is everything up to and including the last
slash; the nondirectory part is the rest.  The rules in VMS syntax are
complicated.

  For some purposes, the nondirectory part is further subdivided into
the name proper and the @dfn{version number}.  On Unix, only backup
files have version numbers in their names; on VMS, every file has a
version number, but most of the time the file name actually used in
Emacs omits the version number.  Version numbers are found mostly in
directory lists.

@defun file-name-directory filename
  This function returns the directory part of @var{filename} (or
@code{nil} if @var{filename} does not include a directory part).  On
Unix, the function returns a string ending in a slash.  On VMS, it
returns a string ending in one of the three characters @samp{:},
@samp{]}, or @samp{>}.

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

@defun file-name-nondirectory filename
  This function returns the nondirectory part of @var{filename}.

@example
@group
(file-name-nondirectory "lewis/foo")
     @result{} "foo"
@end group
@group
(file-name-nondirectory "foo")
     @result{} "foo"
@end group
@group
;; @r{The following example is accurate only on VMS.}
(file-name-nondirectory "[X]FOO.TMP")
     @result{} "FOO.TMP"
@end group
@end example
@end defun

@defun file-name-sans-versions filename
  This function returns @var{filename} without any file version numbers,
backup version numbers, or trailing tildes.

@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
;; @r{The following example applies to VMS only.}
(file-name-sans-versions "foo;23")
     @result{} "foo"
@end group
@end example
@end defun

Karl Heuer's avatar
Karl Heuer committed
1351
@defun file-name-sans-extension filename
Karl Heuer's avatar
Karl Heuer committed
1352 1353 1354 1355 1356 1357 1358 1359 1360 1361
This function returns @var{filename} minus its ``extension,'' if any.
The extension, in a file name, is the part that starts with the last
@samp{.} in the last name component.  For example,

@example
(file-name-sans-extension "foo.lose.c")
     @result{} "foo.lose"
(file-name-sans-extension "big.hack/foo")
     @result{} "big.hack/foo"
@end example
Karl Heuer's avatar
Karl Heuer committed
1362 1363
@end defun

Richard M. Stallman's avatar
Richard M. Stallman committed
1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382
@node Directory Names
@comment  node-name,  next,  previous,  up
@subsection Directory Names
@cindex directory name
@cindex file name of directory

  A @dfn{directory name} is the name of a directory.  A directory is a
kind of file, and it has a file name, which is related to the directory
name but not identical to it.  (This is not quite the same as the usual
Unix terminology.)  These two different names for the same entity are
related by a syntactic transformation.  On Unix, this is simple: a
directory name ends in a slash, whereas the directory's name as a file
lacks that slash.  On VMS, the relationship is more complicated.

  The difference between a directory name and its name as a file is
subtle but crucial.  When an Emacs variable or function argument is
described as being a directory name, a file name of a directory is not
acceptable.

1383 1384 1385
  The following two functions convert between directory names and file
names.  They do nothing special with environment variable substitutions
such as @samp{$HOME}, and the constructs @samp{~}, and @samp{..}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565

@defun file-name-as-directory filename
This function returns a string representing @var{filename} in a form
that the operating system will interpret as the name of a directory.  In
Unix, this means appending a slash to the string.  On VMS, the function
converts a string of the form @file{[X]Y.DIR.1} to the form
@file{[X.Y]}.

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

@defun directory-file-name dirname
This function returns a string representing @var{dirname} in a form
that the operating system will interpret as the name of a file.  On
Unix, this means removing a final slash from the string.  On VMS, the
function converts a string of the form @file{[X.Y]} to
@file{[X]Y.DIR.1}.

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

@cindex directory name abbreviation
  Directory name abbreviations are useful for directories that are
normally accessed through symbolic links.  Sometimes the users recognize
primarily the link's name as ``the name'' of the directory, and find it
annoying to see the directory's ``real'' name.  If you define the link
name as an abbreviation for the ``real'' name, Emacs shows users the
abbreviation instead.

@defvar directory-abbrev-alist
The variable @code{directory-abbrev-alist} contains an alist of
abbreviations to use for file directories.  Each element has the form
@code{(@var{from} . @var{to})}, and says to replace @var{from} with
@var{to} when it appears in a directory name.  The @var{from} string is
actually a regular expression; it should always start with @samp{^}.
The function @code{abbreviate-file-name} performs these substitutions.

You can set this variable in @file{site-init.el} to describe the
abbreviations appropriate for your site.

Here's an example, from a system on which file system @file{/home/fsf}
and so on are normally accessed through symbolic links named @file{/fsf}
and so on.

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

  To convert a directory name to its abbreviation, use this
function:

@defun abbreviate-file-name dirname
This function applies abbreviations from @code{directory-abbrev-alist}
to its argument, and substitutes @samp{~} for the user's home
directory.
@end defun

@node Relative File Names
@subsection Absolute and Relative File Names
@cindex absolute file name
@cindex relative file name

  All the directories in the file system form a tree starting at the
root directory.  A file name can specify all the directory names
starting from the root of the tree; then it is called an @dfn{absolute}
file name.  Or it can specify the position of the file in the tree
relative to a default directory; then it is called a @dfn{relative}
file name.  On Unix, an absolute file name starts with a slash or a
tilde (@samp{~}), and a relative one does not.  The rules on VMS are
complicated.

@defun file-name-absolute-p filename
This function returns @code{t} if file @var{filename} is an absolute
file name, @code{nil} otherwise.  On VMS, this function understands both
Unix syntax and VMS syntax.

@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
@subsection Functions that Expand Filenames
@cindex expansion of file names

  @dfn{Expansion} of a file name means converting a relative file name
to an absolute one.  Since this is done relative to a default directory,
you must specify the default directory name as well as the file name to
be expanded.  Expansion also simplifies file names by eliminating
redundancies such as @file{./} and @file{@var{name}/../}.

@defun expand-file-name filename &optional directory
This function converts @var{filename} to an absolute file name.  If
@var{directory} is supplied, it is the directory to start with if
@var{filename} is relative.  (The value of @var{directory} should itself
be an absolute directory name; it may start with @samp{~}.)
Otherwise, the current buffer's value of @code{default-directory} is
used.  For example:

@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

Filenames containing @samp{.} or @samp{..} are simplified to their
canonical form:

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

@samp{~/} is expanded into the user's home directory.  A @samp{/} or
@samp{~} following a @samp{/} is taken to be the start of an absolute
file name that overrides what precedes it, so everything before that
@samp{/} or @samp{~} is deleted.  For example:

@example
@group
(expand-file-name 
 "/a1/gnu//usr/local/lib/emacs/etc/MACHINES")
     @result{} "/usr/local/lib/emacs/etc/MACHINES"
@end group
@group
(expand-file-name "/a1/gnu/~/foo")
     @result{} "/xcssun/users/rms/foo"
@end group
@end example

@noindent
In both cases, @file{/a1/gnu/} is discarded because an absolute file
name follows it.

Note that @code{expand-file-name} does @emph{not} expand environment
variables; only @code{substitute-in-file-name} does that.
@end defun

@c Emacs 19 feature
@defun file-relative-name filename directory
This function does the inverse of expansion---it tries to return a
1566
relative name that is equivalent to @var{filename} when interpreted
1567 1568 1569 1570 1571 1572 1573
relative to @var{directory}.

On some operating systems, an absolute file name begins with a device
name.  On such systems, @var{filename} has no relative equivalent based
on @var{directory} if they start with two different device names.  In
this case, @code{file-relative-name} returns @var{filename} in absolute
form.
Richard M. Stallman's avatar
Richard M. Stallman committed
1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658

@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
The value of this buffer-local variable is the default directory for the
current buffer.  It should be an absolute directory name; it may start
with @samp{~}.  This variable is local in every buffer.

@code{expand-file-name} uses the default directory when its second
argument is @code{nil}.

On Unix systems, the value is always a string ending with a slash.

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

@defun substitute-in-file-name filename
This function replaces environment variables references in
@var{filename} with the environment variable values.  Following standard
Unix shell syntax, @samp{$} is the prefix to substitute an environment
variable value.

The environment variable name is the series of alphanumeric characters
(including underscores) that follow the @samp{$}.  If the character following
the @samp{$} is a @samp{@{}, then the variable name is everything up to the
matching @samp{@}}.

@c Wordy to avoid overfull hbox.  --rjc 15mar92
Here we assume that the environment variable @code{HOME}, which holds
the user's home directory name, has value @samp{/xcssun/users/rms}.

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

If a @samp{~} or a @samp{/} appears following a @samp{/}, after
substitution, everything before the following @samp{/} is discarded:

@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"
@end group
@end example

On VMS, @samp{$} substitution is not done, so this function does nothing
on VMS except discard superfluous initial components as shown above.
@end defun

@node Unique File Names
@subsection Generating Unique File Names

  Some programs need to write temporary files.  Here is the usual way to
construct a name for such a file:

@example
(make-temp-name (concat "/tmp/" @var{name-of-application}))
@end example

@noindent
Here we use the directory @file{/tmp/} because that is the standard
place on Unix for temporary files.  The job of @code{make-temp-name} is
to prevent two different users or two different jobs from trying to use
the same name.

@defun make-temp-name string
This function generates string that can be used as a unique name.  The
1659 1660
name starts with @var{string}, and ends with a number that is different
in each Emacs job.
Richard M. Stallman's avatar
Richard M. Stallman committed
1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693

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

To prevent conflicts among different libraries running in the same
Emacs, each Lisp program that uses @code{make-temp-name} should have its
own @var{string}.  The number added to the end of the name distinguishes
between the same application running in different Emacs jobs.
@end defun

@node File Name Completion
@subsection File Name Completion
@cindex file name completion subroutines
@cindex completion, file name

  This section describes low-level subroutines for completing a file
name.  For other completion functions, see @ref{Completion}.

@defun file-name-all-completions partial-filename directory
This function returns a list of all possible completions for a file
whose name starts with @var{partial-filename} in directory
@var{directory}.  The order of the completions is the order of the files
in the directory, which is unpredictable and conveys no useful
information.

The argument @var{partial-filename} must be a file name containing no
directory part and no slash.  The current buffer's default directory is
prepended to @var{directory}, if @var{directory} is not absolute.

1694 1695
In the following example, suppose that @file{~rms/lewis} is the current
default directory, and has five files whose names begin with @samp{f}:
Richard M. Stallman's avatar
Richard M. Stallman committed
1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765
@file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
@file{file.c.~2~}.@refill

@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
This function completes the file name @var{filename} in directory
@var{directory}.  It returns the longest prefix common to all file names
in directory @var{directory} that start with @var{filename}.

If only one match exists and @var{filename} matches it exactly, the
function returns @code{t}.  The function returns @code{nil} if directory
@var{directory} contains no name starting with @var{filename}.

In the following example, suppose that the current default directory
has five files whose names begin with @samp{f}: @file{foo},
@file{file~}, @file{file.c}, @file{file.c.~1~}, and
@file{file.c.~2~}.@refill

@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
@code{file-name-completion} usually ignores file names that end in any
string in this list.  It does not ignore them when all the possible
completions end in one of these suffixes or when a buffer showing all
possible completions is displayed.@refill

A typical value might look like this:

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

1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812
@node Standard File Names
@subsection Standard File Names

  Most of the file names used in Lisp programs are entered by the user.
But occasionally a Lisp program needs to specify a standard file name
for a particular use---typically, to hold customization information
about each user.  For example, abbrev definitions are stored (by
default) in the file @file{~/.abbrev_defs}; the @code{completion}
package stores completions in the file @file{~/.completions}.  These are
two of the many standard file names used by parts of Emacs for certain
purposes.

  Various operating systems have their own conventions for valid file
names and for which file names to use for user profile data.  A Lisp
program which reads a file using a standard file name ought to use, on
each type of system, a file name suitable for that system.  The function
@code{convert-standard-filename} makes this easy to do.

@defun convert-standard-filename filename
This function alters the file name @var{filename} to fit the conventions
of the operating system in use, and returns the result as a new string.
@end defun

  The recommended way to specify a standard file name in a Lisp program
is to choose a name which fits the conventions of GNU and Unix systems,
usually with a nondirectory part that starts with a period, and pass it
to @code{convert-standard-filename} instead of using it directly.  Here
is an example from the @code{completion} package:

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

  On GNU and Unix systems, and on some other systems as well,
@code{convert-standard-filename} returns its argument unchanged.  On
some other systems, it alters the name to fit the systems's conventions.

  For example, on MS-DOS the alterations made by this function include
converting a leading @samp{.}  to @samp{_}, converting a @samp{_} in the
middle of the name to @samp{.} if there is no other @samp{.}, inserting
a @samp{.} after eight characters if there is none, and truncating to
three characters after the @samp{.}.  (It makes other changes as well.)
Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
@file{.completions} becomes @file{_complet.ion}.

Richard M. Stallman's avatar
Richard M. Stallman committed
1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855