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

17 18
  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
19
expand file name arguments by calling @code{expand-file-name}, so that
20 21 22 23
@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}.

24 25 26 27 28 29
  When file I/O functions signal Lisp errors, they usually use the
condition @code{file-error} (@pxref{Handling Errors}).  The error
message is in most cases obtained from the operating system, according
to locale @code{system-message-locale}, and decoded using coding system
@code{locale-coding-system} (@pxref{Locales}).

Richard M. Stallman's avatar
Richard M. Stallman committed
30 31 32 33 34 35 36 37
@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.
38
* Changing Files::           Renaming files, changing protection, etc.
Richard M. Stallman's avatar
Richard M. Stallman committed
39 40 41 42 43
* 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
44
* Format Conversion::        Conversion to and from various file formats.
Richard M. Stallman's avatar
Richard M. Stallman committed
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68
@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,
69
``I am editing a file,'' rather than, ``I am editing a buffer that I
Richard M. Stallman's avatar
Richard M. Stallman committed
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
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
88 89 90 91 92
  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}.

93
@deffn Command find-file filename &optional wildcards
Richard M. Stallman's avatar
Richard M. Stallman committed
94
This command selects a buffer visiting the file @var{filename},
95
using an existing buffer if there is one, and otherwise creating a
Richard M. Stallman's avatar
Richard M. Stallman committed
96 97
new buffer and reading the file into it.  It also returns that buffer.

98 99
Aside from some technical details, the body of the @code{find-file}
function is basically equivalent to:
Richard M. Stallman's avatar
Richard M. Stallman committed
100 101

@example
102
(switch-to-buffer (find-file-noselect filename nil nil wildcards))
Richard M. Stallman's avatar
Richard M. Stallman committed
103 104 105 106 107
@end example

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

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

Richard M. Stallman's avatar
Richard M. Stallman committed
112 113 114 115
When @code{find-file} is called interactively, it prompts for
@var{filename} in the minibuffer.
@end deffn

116
@defun find-file-noselect filename &optional nowarn rawfile wildcards
Richard M. Stallman's avatar
Richard M. Stallman committed
117 118 119 120 121 122
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.

Karl Heuer's avatar
Karl Heuer committed
123 124
If @var{wildcards} is non-@code{nil},
then @code{find-file-noselect} expands wildcard
125 126
characters in @var{filename} and visits all the matching files.

Richard M. Stallman's avatar
Richard M. Stallman committed
127 128 129 130 131 132
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.

133
This function displays warning or advisory messages in various peculiar
134 135
cases, unless the optional argument @var{nowarn} is non-@code{nil}.  For
example, if it needs to create a buffer, and there is no file named
136
@var{filename}, it displays the message @samp{(New file)} in the echo
137
area, and leaves the buffer empty.
138 139 140 141 142 143

The @code{find-file-noselect} function normally 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
Stefan Monnier's avatar
Stefan Monnier committed
144
@code{find-file-hook}.
145 146 147

If the optional argument @var{rawfile} is non-@code{nil}, then
@code{after-find-file} is not called, and the
Stefan Monnier's avatar
Stefan Monnier committed
148
@code{find-file-not-found-functions} are not run in case of failure.  What's
149 150 151
more, a non-@code{nil} @var{rawfile} value suppresses coding system
conversion (@pxref{Coding Systems}) and format conversion (@pxref{Format
Conversion}).
Richard M. Stallman's avatar
Richard M. Stallman committed
152

153 154
The @code{find-file-noselect} function usually returns the buffer that
is visiting the file @var{filename}.  But, if wildcards are actually
Gerd Moellmann's avatar
Gerd Moellmann committed
155
used and expanded, it returns a list of buffers that are visiting the
156
various files.
Richard M. Stallman's avatar
Richard M. Stallman committed
157 158 159 160 161 162 163 164 165

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

166
@deffn Command find-file-other-window filename &optional wildcards
Richard M. Stallman's avatar
Richard M. Stallman committed
167 168 169 170 171 172 173 174
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

175
@deffn Command find-file-read-only filename &optional wildcards
Richard M. Stallman's avatar
Richard M. Stallman committed
176 177 178 179 180 181 182 183 184
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
185 186 187 188
This command visits @var{filename} using View mode, returning to the
previous buffer when you exit View mode.  View mode is a minor mode that
provides commands to skim rapidly through the file, but does not let you
modify the text.  Entering View mode runs the normal hook
Karl Heuer's avatar
Karl Heuer committed
189
@code{view-mode-hook}.  @xref{Hooks}.
Richard M. Stallman's avatar
Richard M. Stallman committed
190 191 192 193 194

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

195
@tindex find-file-wildcards
196
@defopt find-file-wildcards
197 198
If this variable is non-@code{nil}, then the various @code{find-file}
commands check for wildcard characters and visit all the files that
199 200 201 202 203
match them (when invoked interactively or when their @var{wildcards}
argument is non-@code{nil}).  If this option is @code{nil}, then
the @code{find-file} commands ignore their @var{wildcards} argument
and never treat wildcard characters specially.
@end defopt
204

Stefan Monnier's avatar
Stefan Monnier committed
205
@defvar find-file-hook
Richard M. Stallman's avatar
Richard M. Stallman committed
206 207 208 209 210
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.

211
This variable is a normal hook.  @xref{Hooks}.
Richard M. Stallman's avatar
Richard M. Stallman committed
212 213
@end defvar

Stefan Monnier's avatar
Stefan Monnier committed
214
@defvar find-file-not-found-functions
Richard M. Stallman's avatar
Richard M. Stallman committed
215 216 217 218 219 220 221 222
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
223
used, and in many cases only some of the functions are called.
Richard M. Stallman's avatar
Richard M. Stallman committed
224 225 226 227 228 229
@end defvar

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

230 231 232
  The @code{find-file-noselect} function uses two important subroutines
which are sometimes useful in user Lisp code: @code{create-file-buffer}
and @code{after-find-file}.  This section explains how to use them.
Richard M. Stallman's avatar
Richard M. Stallman committed
233 234 235 236 237 238 239 240 241

@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
242
It also does not use the default major mode.
Richard M. Stallman's avatar
Richard M. Stallman committed
243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262

@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

263
@defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
Richard M. Stallman's avatar
Richard M. Stallman committed
264 265 266 267 268 269 270 271 272
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:
273
@samp{(New file)}.  For more serious errors, the caller should usually not
Richard M. Stallman's avatar
Richard M. Stallman committed
274 275 276 277 278
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.

279 280 281 282 283 284 285 286 287 288
If @var{noauto} is non-@code{nil}, that says not to enable or disable
Auto-Save mode.  The mode remains enabled if it was enabled before.

If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
means this call was from @code{revert-buffer}.  This has no direct
effect, but some mode functions and hook functions check the value
of this variable.

If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
major mode, don't process local variables specifications in the file,
Stefan Monnier's avatar
Stefan Monnier committed
289
and don't run @code{find-file-hook}.  This feature is used by
290 291
@code{revert-buffer} in some cases.

Richard M. Stallman's avatar
Richard M. Stallman committed
292
The last thing @code{after-find-file} does is call all the functions
Stefan Monnier's avatar
Stefan Monnier committed
293
in the list @code{find-file-hook}.
Richard M. Stallman's avatar
Richard M. Stallman committed
294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311
@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
312 313 314
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
315 316 317 318 319 320 321 322 323 324 325

@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.
326 327 328

@item
With an argument of 0, unconditionally do @emph{not} make any backup file.
Richard M. Stallman's avatar
Richard M. Stallman committed
329 330 331
@end itemize
@end deffn

332
@anchor{Definition of save-some-buffers}
333
@deffn Command save-some-buffers &optional save-silently-p pred
Richard M. Stallman's avatar
Richard M. Stallman committed
334 335 336 337 338
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.

339 340
The optional @var{pred} argument controls which buffers to ask about
(or to save silently if @var{save-silently-p} is non-@code{nil}).
341 342 343 344 345 346 347 348 349 350 351 352
If it is @code{nil}, that means to ask only about file-visiting buffers.
If it is @code{t}, that means also offer to save certain other non-file
buffers---those that have a non-@code{nil} buffer-local value of
@code{buffer-offer-save}.  (A user who says @samp{yes} to saving a
non-file buffer is asked to specify the file name to use.)  The
@code{save-buffers-kill-emacs} function passes the value @code{t} for
@var{pred}.

If @var{pred} is neither @code{t} nor @code{nil}, then it should be
a function of no arguments.  It will be called in each buffer to decide
whether to offer to save that buffer.  If it returns a non-@code{nil}
value in a certain buffer, that means do offer to save that buffer.
Richard M. Stallman's avatar
Richard M. Stallman committed
353 354
@end deffn

355
@anchor{Definition of write-file}
356
@deffn Command write-file filename &optional confirm
Richard M. Stallman's avatar
Richard M. Stallman committed
357 358 359 360
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
361 362
calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
@code{save-buffer}.
363 364

If @var{confirm} is non-@code{nil}, that means to ask for confirmation
365 366 367 368 369 370 371
before overwriting an existing file.  Interactively, confirmation is
required, unless the user supplies a prefix argument.

If @var{filename} is an existing directory, or a symbolic link to one,
@code{write-file} uses the name of the visited file, in directory
@var{filename}.  If the buffer is not visiting a file, it uses the
buffer name instead.
Richard M. Stallman's avatar
Richard M. Stallman committed
372 373
@end deffn

374 375 376 377
  Saving a buffer runs several hooks.  It also performs format
conversion (@pxref{Format Conversion}), and may save text properties in
``annotations'' (@pxref{Saving Properties}).

Stefan Monnier's avatar
Stefan Monnier committed
378
@defvar write-file-functions
Richard M. Stallman's avatar
Richard M. Stallman committed
379 380 381 382 383 384
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.

Stefan Monnier's avatar
Stefan Monnier committed
385
If a function in @code{write-file-functions} returns non-@code{nil}, it
Richard M. Stallman's avatar
Richard M. Stallman committed
386 387 388 389 390 391 392 393
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
394 395 396
@code{backup-buffer} and use that (if non-@code{nil}) to set the mode
bits of the file that you write.  This is what @code{save-buffer}
normally does. @xref{Making Backups,, Making Backup Files}.
Richard M. Stallman's avatar
Richard M. Stallman committed
397

Stefan Monnier's avatar
Stefan Monnier committed
398
The hook functions in @code{write-file-functions} are also responsible for
399 400 401
encoding the data (if desired): they must choose a suitable coding
system (@pxref{Lisp and Coding Systems}), perform the encoding
(@pxref{Explicit Encoding}), and set @code{last-coding-system-used} to
402
the coding system that was used (@pxref{Encoding and I/O}).
403

Stefan Monnier's avatar
Stefan Monnier committed
404 405 406 407 408 409 410
If you set this hook locally in a buffer, it is assumed to be
associated with the file or the way the contents of the buffer were
obtained.  Thus the variable is marked as a permanent local, so that
changing the major mode does not alter a buffer-local value.  On the
other hand, calling @code{set-visited-file-name} will reset it.
If this is not what you want, you might like to use
@code{write-contents-functions} instead.
411

Richard M. Stallman's avatar
Richard M. Stallman committed
412 413 414 415 416
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
Stefan Monnier's avatar
Stefan Monnier committed
417 418
@defvar write-contents-functions
This works just like @code{write-file-functions}, but it is intended for
Richard M. Stallman's avatar
Richard M. Stallman committed
419
hooks that pertain to the contents of the file, as opposed to hooks that
Richard M. Stallman's avatar
Richard M. Stallman committed
420
pertain to where the file came from.  Such hooks are usually set up by
421 422 423
major modes, as buffer-local bindings for this variable.  If any of the
functions in this hook returns non-@code{nil}, @code{write-file-functions}
is not run.
424 425

This variable automatically becomes buffer-local whenever it is set;
426 427
switching to a new major mode always resets this variable, but
calling @code{set-visited-file-name} does not.
Richard M. Stallman's avatar
Richard M. Stallman committed
428 429
@end defvar

430 431 432
@defopt before-save-hook
This normal hook runs before a buffer is saved in its visited file,
regardless of whether that is done normally or by one of the hooks
Luc Teirlinck's avatar
Luc Teirlinck committed
433 434 435
described above.  For instance, the @file{copyright.el} program uses
this hook to make sure the file you are saving has the current year in
its copyright notice.
436
@end defopt
437

Richard M. Stallman's avatar
Richard M. Stallman committed
438
@c Emacs 19 feature
439
@defopt after-save-hook
Richard M. Stallman's avatar
Richard M. Stallman committed
440
This normal hook runs after a buffer has been saved in its visited file.
441 442
One use of this hook is in Fast Lock mode; it uses this hook to save the
highlighting information in a cache file.
443
@end defopt
Richard M. Stallman's avatar
Richard M. Stallman committed
444

445
@defopt file-precious-flag
Richard M. Stallman's avatar
Richard M. Stallman committed
446 447 448 449 450 451 452
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
453 454 455
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
456

457
Some modes give this variable a non-@code{nil} buffer-local value
458
in particular buffers.
459
@end defopt
Richard M. Stallman's avatar
Richard M. Stallman committed
460 461 462 463 464 465 466 467 468 469 470 471 472 473 474

@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

475 476
  See also the function @code{set-visited-file-name} (@pxref{Buffer File
Name}).
477

Richard M. Stallman's avatar
Richard M. Stallman committed
478 479 480 481 482 483 484 485 486 487
@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
488
current buffer after point.  It returns a list of the absolute file name
Richard M. Stallman's avatar
Richard M. Stallman committed
489 490 491
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
492 493 494 495
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
496 497 498
Properties}.  Normally, one of the functions in the
@code{after-insert-file-functions} list determines the coding system
(@pxref{Coding Systems}) used for decoding the file's contents.
Richard M. Stallman's avatar
Richard M. Stallman committed
499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521

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.
522

523 524 525
It is possible to read a special file (such as a FIFO or an I/O device)
with @code{insert-file-contents}, as long as @var{replace} and
@var{visit} are @code{nil}.
526 527 528 529 530 531
@end defun

@defun insert-file-contents-literally filename &optional visit beg end replace
This function works like @code{insert-file-contents} except that it does
not do format decoding (@pxref{Format Conversion}), does not do
character code conversion (@pxref{Coding Systems}), does not run
Stefan Monnier's avatar
Stefan Monnier committed
532
@code{find-file-hook}, does not perform automatic uncompression, and so
533
on.
Richard M. Stallman's avatar
Richard M. Stallman committed
534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557
@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.
558 559 560 561 562 563

When called from Lisp, this function is completely equivalent to:

@example
(write-region start end filename t)
@end example
Richard M. Stallman's avatar
Richard M. Stallman committed
564 565
@end deffn

566
@deffn Command write-region start end filename &optional append visit lockname mustbenew
Richard M. Stallman's avatar
Richard M. Stallman committed
567 568 569
This function writes the region delimited by @var{start} and @var{end}
in the current buffer into the file specified by @var{filename}.

570 571 572 573
If @var{start} is @code{nil}, then the command writes the entire buffer
contents (@emph{not} just the accessible portion) to the file and
ignores @var{end}.

Richard M. Stallman's avatar
Richard M. Stallman committed
574 575
@c Emacs 19 feature
If @var{start} is a string, then @code{write-region} writes or appends
576 577
that string, rather than text from the buffer.  @var{end} is ignored in
this case.
Richard M. Stallman's avatar
Richard M. Stallman committed
578 579

If @var{append} is non-@code{nil}, then the specified text is appended
Dave Love's avatar
Dave Love committed
580 581 582
to the existing file contents (if any).  Starting in Emacs 21, if
@var{append} is an integer, then @code{write-region} seeks to that byte
offset from the start of the file and writes the data from there.
Richard M. Stallman's avatar
Richard M. Stallman committed
583

584
If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
585
for confirmation if @var{filename} names an existing file.
586
Starting in Emacs 21, if @var{mustbenew} is the symbol @code{excl},
587 588 589 590 591 592 593 594
then @code{write-region} does not ask for confirmation, but instead
it signals an error @code{file-already-exists} if the file already
exists.

The test for an existing file, when @var{mustbenew} is @code{excl}, uses
a special system feature.  At least for files on a local disk, there is
no chance that some other program could create a file of the same name
before Emacs does, without Emacs's noticing.
595

Richard M. Stallman's avatar
Richard M. Stallman committed
596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611
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.

612 613 614 615
The optional argument @var{lockname}, if non-@code{nil}, specifies the
file name to use for purposes of locking and unlocking, overriding
@var{filename} and @var{visit} for that purpose.

Karl Heuer's avatar
Karl Heuer committed
616 617 618 619
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
620

621
Normally, @code{write-region} displays the message @samp{Wrote
Richard M. Stallman's avatar
Richard M. Stallman committed
622 623 624
@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,
625
files that the user does not need to know about.
Richard M. Stallman's avatar
Richard M. Stallman committed
626 627
@end deffn

628
@anchor{Definition of with-temp-file}
629
@defmac with-temp-file file body...
630 631 632 633 634 635
The @code{with-temp-file} macro evaluates the @var{body} forms with a
temporary buffer as the current buffer; then, at the end, it writes the
buffer contents into file @var{file}.  It kills the temporary buffer
when finished, restoring the buffer that was current before the
@code{with-temp-file} form.  Then it returns the value of the last form
in @var{body}.
636 637 638 639

The current buffer is restored even in case of an abnormal exit via
@code{throw} or error (@pxref{Nonlocal Exits}).

640 641
See also @code{with-temp-buffer} in @ref{Definition of
with-temp-buffer,, The Current Buffer}.
642 643
@end defmac

Richard M. Stallman's avatar
Richard M. Stallman committed
644 645 646 647 648 649 650 651 652
@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.
653 654
The file lock is really a file, a symbolic link with a special name,
stored in the same directory as the file you are editing.
Richard M. Stallman's avatar
Richard M. Stallman committed
655

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

@defun file-locked-p filename
665 666 667 668
This function returns @code{nil} if the file @var{filename} is not
locked.  It returns @code{t} if it is locked by this Emacs process, and
it returns the name of the user who has locked it if it is locked by
some other job.
Richard M. Stallman's avatar
Richard M. Stallman committed
669 670 671 672 673 674 675 676 677 678

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

@defun lock-buffer &optional filename
679
This function locks the file @var{filename}, if the current buffer is
Richard M. Stallman's avatar
Richard M. Stallman committed
680 681 682 683 684 685 686 687 688 689 690 691
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

692 693 694 695
  File locking is not supported on some systems.  On systems that do not
support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
@code{file-locked-p} do nothing and return @code{nil}.

Richard M. Stallman's avatar
Richard M. Stallman committed
696 697
@defun ask-user-about-lock file other-user
This function is called when the user tries to modify @var{file}, but it
698 699 700
is locked by another user named @var{other-user}.  The default
definition of this function asks the user to say what to do.  The value
this function returns determines what Emacs does next:
Richard M. Stallman's avatar
Richard M. Stallman committed
701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726

@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

727 728
If you wish, you can replace the @code{ask-user-about-lock} function
with your own version that makes the decision in another way.  The code
Richard M. Stallman's avatar
Richard M. Stallman committed
729 730 731 732 733 734
for its usual definition is in @file{userlock.el}.
@end defun

@node Information about Files
@section Information about Files

735 736 737 738 739
  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
740 741 742 743 744 745 746 747 748 749 750 751 752 753

@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

754 755 756 757
  These functions test for permission to access a file in specific
ways.  Unless explicitly stated otherwise, they recursively follow
symbolic links for their file name arguments, at all levels (at the
level of the file itself and at all levels of parent directories).
Richard M. Stallman's avatar
Richard M. Stallman committed
758 759

@defun file-exists-p filename
Richard M. Stallman's avatar
Richard M. Stallman committed
760 761 762 763 764 765
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 and GNU/Linux, this is
true if the file exists and you have execute permission on the
containing directories, regardless of the protection of the file
itself.)
Richard M. Stallman's avatar
Richard M. Stallman committed
766 767 768 769

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}.
Richard M. Stallman's avatar
Richard M. Stallman committed
770 771 772 773 774

Directories are files, so @code{file-exists-p} returns @code{t} when
given a directory name.  However, symbolic links are treated
specially; @code{file-exists-p} returns @code{t} for a symbolic link
name only if the target file exists.
Richard M. Stallman's avatar
Richard M. Stallman committed
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
@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
800 801 802 803
you can execute it.  It returns @code{nil} otherwise.  On Unix and
GNU/Linux, 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.
Richard M. Stallman's avatar
Richard M. Stallman committed
804 805 806
@end defun

@defun file-writable-p filename
807 808 809 810 811
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
812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835

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
836 837 838
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
839
file which is a directory.
Richard M. Stallman's avatar
Richard M. Stallman committed
840 841 842 843 844 845 846 847 848 849 850 851 852

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

853 854 855 856 857 858
@defun access-file filename string
This function opens file @var{filename} for reading, then closes it and
returns @code{nil}.  However, if the open fails, it signals an error
using @var{string} as the error message text.
@end defun

Karl Heuer's avatar
Karl Heuer committed
859 860
@defun file-ownership-preserved-p filename
This function returns @code{t} if deleting the file @var{filename} and
861 862 863 864 865 866 867
then creating it anew would keep the file's owner unchanged.  It also
returns @code{t} for nonexistent files.

If @var{filename} is a symbolic link, then, unlike the other functions
discussed here, @code{file-ownership-preserved-p} does @emph{not}
replace @var{filename} with its target.  However, it does recursively
follow symbolic links at all levels of parent directories.
Karl Heuer's avatar
Karl Heuer committed
868 869
@end defun

Richard M. Stallman's avatar
Richard M. Stallman committed
870 871 872
@defun file-newer-than-file-p filename1 filename2
@cindex file age
@cindex file modification time
873
This function returns @code{t} if the file @var{filename1} is
Richard M. Stallman's avatar
Richard M. Stallman committed
874
newer than file @var{filename2}.  If @var{filename1} does not
875 876
exist, it returns @code{nil}.  If @var{filename1} does exist, but
@var{filename2} does not, it returns @code{t}.
Richard M. Stallman's avatar
Richard M. Stallman committed
877

878 879 880
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
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

@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
909 910
  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
911 912 913

@defun file-symlink-p filename
@cindex file symbolic links
914
If the file @var{filename} is a symbolic link, the
915 916 917 918
@code{file-symlink-p} function returns the (non-recursive) link target
as a string.  (Determining the file name that the link points to from
the target is nontrivial.)  First, this function recursively follows
symbolic links at all levels of parent directories.
Richard M. Stallman's avatar
Richard M. Stallman committed
919 920

If the file @var{filename} is not a symbolic link (or there is no such file),
921
@code{file-symlink-p} returns @code{nil}.
Richard M. Stallman's avatar
Richard M. Stallman committed
922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944

@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

945 946 947
The next two functions recursively follow symbolic links at
all levels for @var{filename}.

Richard M. Stallman's avatar
Richard M. Stallman committed
948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976
@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
977 978
@defun file-regular-p filename
This function returns @code{t} if the file @var{filename} exists and is
979
a regular file (not a directory, named pipe, terminal, or
Karl Heuer's avatar
Karl Heuer committed
980 981 982
other I/O device).
@end defun

Richard M. Stallman's avatar
Richard M. Stallman committed
983 984 985 986 987 988
@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
989 990 991 992 993 994
symbolic links at all levels until none remain, then simplifying away
@samp{.}@: and @samp{..}@: appearing as name components.  This results
in a sort of canonical name for the file.  A file does not always 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.
Richard M. Stallman's avatar
Richard M. Stallman committed
995 996

@defun file-truename filename
997 998
The function @code{file-truename} returns the truename of the file
@var{filename}.  The argument must be an absolute file name.
999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012

This function does not expand environment variables.  Only
@code{substitute-in-file-name} does that.  @xref{Definition of
substitute-in-file-name}.

If you may need to follow symbolic links preceding @samp{..}@:
appearing as a name component, you should make sure to call
@code{file-truename} without prior direct or indirect calls to
@code{expand-file-name}, as otherwise the file name component
immediately preceding @samp{..} will be ``simplified away'' before
@code{file-truename} is called.  To eliminate the need for a call to
@code{expand-file-name}, @code{file-truename} handles @samp{~} in the
same way that @code{expand-file-name} does.  @xref{File Name
Expansion,, Functions that Expand Filenames}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1013 1014
@end defun

1015
@defun file-chase-links filename &optional limit
1016 1017
This function follows symbolic links, starting with @var{filename},
until it finds a file name which is not the name of a symbolic link.
1018 1019 1020 1021 1022 1023
Then it returns that file name.  This function does @emph{not} follow
symbolic links at the level of parent directories.

If you specify a number for @var{limit}, then after chasing through
that many links, the function just returns what it has even if that is
still a symbolic link.
1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040
@end defun

  To illustrate the difference between @code{file-chase-links} and
@code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
the directory @file{/home/foo}, and @file{/home/foo/hello} is an
ordinary file (or at least, not a symbolic link) or nonexistent.  Then
we would have:

@example
(file-chase-links "/usr/foo/hello")
     ;; @r{This does not follow the links in the parent directories.}
     @result{} "/usr/foo/hello"
(file-truename "/usr/foo/hello")
     ;; @r{Assuming that @file{/home} is not a symbolic link.}
     @result{} "/home/foo/hello"
@end example

Richard M. Stallman's avatar
Richard M. Stallman committed
1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058
  @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,
1059
then the file is executable by all users, if the second-lowest-order bit
Richard M. Stallman's avatar
Richard M. Stallman committed
1060 1061 1062
is 1, then the file is writable by all users, etc.

The highest value returnable is 4095 (7777 octal), meaning that
1063
everyone has read, write, and execute permission, that the @acronym{SUID} bit
Richard M. Stallman's avatar
Richard M. Stallman committed
1064 1065
is set for both others and group, and that the sticky bit is set.

1066 1067 1068 1069
If @var{filename} does not exist, @code{file-modes} returns @code{nil}.

This function recursively follows symbolic links at all levels.

Richard M. Stallman's avatar
Richard M. Stallman committed
1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096
@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

1097 1098 1099 1100 1101
If the @var{filename} argument to the next two functions is a symbolic
link, then these function do @emph{not} replace it with its target.
However, they both recursively follow symbolic links at all levels of
parent directories.

Richard M. Stallman's avatar
Richard M. Stallman committed
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
@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

1127
@anchor{Definition of file-attributes}
1128
@defun file-attributes filename &optional id-format
Richard M. Stallman's avatar
Richard M. Stallman committed
1129 1130
This function returns a list of attributes of file @var{filename}.  If
the specified file cannot be opened, it returns @code{nil}.
1131 1132 1133 1134 1135 1136
The optional parameter @var{id-format} specifies the preferred format
of attributes @acronym{UID} and @acronym{GID} (see below)---the
valid values are @code{'string} and @code{'integer}.  The latter is
the default, but we plan to change that, so you should specify a
non-@code{nil} value for @var{id-format} if you use the returned
@acronym{UID} or @acronym{GID}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148

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
1149
(@pxref{Changing Files}).
Richard M. Stallman's avatar
Richard M. Stallman committed
1150 1151

@item
1152 1153
The file's @acronym{UID} as a string or an integer.  If a string
value cannot be looked up, the integer value is returned.
Richard M. Stallman's avatar
Richard M. Stallman committed
1154 1155

@item
1156
The file's @acronym{GID} likewise.
Richard M. Stallman's avatar
Richard M. Stallman committed
1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170

@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
1171 1172
The size of the file in bytes.  If the size is too large to fit in a
Lisp integer, this is a floating point number.
Richard M. Stallman's avatar
Richard M. Stallman committed
1173 1174

@item
1175
The file's modes, as a string of ten letters or dashes,
Richard M. Stallman's avatar
Richard M. Stallman committed
1176 1177 1178
as in @samp{ls -l}.

@item
1179
@code{t} if the file's @acronym{GID} would change if file were
Richard M. Stallman's avatar
Richard M. Stallman committed
1180 1181 1182
deleted and recreated; @code{nil} otherwise.

@item
1183 1184 1185 1186
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
1187 1188

@item
1189 1190 1191 1192
The file system number of the file system that the file is in.
Depending on the magnitude of the value, this can be either an integer
or a cons cell, in the same manner as the inode number.  This element
and the file's inode number together give enough information to
1193 1194
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
1195 1196 1197 1198 1199 1200
@end enumerate

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

@example
@group
1201 1202
(file-attributes "files.texi" 'string)
     @result{}  (nil 1 "lh" "users"
1203 1204
          (8489 20284)
          (8489 20284)
Richard M. Stallman's avatar
Richard M. Stallman committed
1205
          (8489 20285)
1206
          14906 "-rw-rw-rw-"
1207
          nil 129500 -32252)
Richard M. Stallman's avatar
Richard M. Stallman committed
1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221
@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).

1222 1223
@item "lh"
is owned by the user with name "lh".
Richard M. Stallman's avatar
Richard M. Stallman committed
1224