2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/files.info
8 @node Files, Backups and Auto-Saving, Documentation, Top
11 In SXEmacs, you can find, create, view, save, and otherwise work with
12 files and file directories. This chapter describes most of the
13 file-related functions of SXEmacs Lisp, but a few others are described in
14 @ref{Buffers}, and those related to backups and auto-saving are
15 described in @ref{Backups and Auto-Saving}.
17 Many of the file functions take one or more arguments that are file
18 names. A file name is actually a string. Most of these functions
19 expand file name arguments using @code{expand-file-name}, so that
20 @file{~} is handled correctly, as are relative file names (including
21 @samp{../}). These functions don't recognize environment variable
22 substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
25 * Visiting Files:: Reading files into SXEmacs buffers for editing.
26 * Saving Buffers:: Writing changed buffers back into files.
27 * Reading from Files:: Reading files into buffers without visiting.
28 * Writing to Files:: Writing new files from parts of buffers.
29 * File Locks:: Locking and unlocking files, to prevent
30 simultaneous editing by two people.
31 * Information about Files:: Testing existence, accessibility, size of files.
32 * Changing File Attributes:: Renaming files, changing protection, etc.
33 * File Names:: Decomposing and expanding file names.
34 * Contents of Directories:: Getting a list of the files in a directory.
35 * Create/Delete Dirs:: Creating and Deleting Directories.
36 * Magic File Names:: Defining "magic" special handling
37 for certain file names.
38 * Partial Files:: Treating a section of a buffer as a file.
39 * Format Conversion:: Conversion to and from various file formats.
44 @section Visiting Files
46 @cindex visiting files
48 Visiting a file means reading a file into a buffer. Once this is
49 done, we say that the buffer is @dfn{visiting} that file, and call the
50 file ``the visited file'' of the buffer.
52 A file and a buffer are two different things. A file is information
53 recorded permanently in the computer (unless you delete it). A buffer,
54 on the other hand, is information inside of SXEmacs that will vanish at
55 the end of the editing session (or when you kill the buffer). Usually,
56 a buffer contains information that you have copied from a file; then we
57 say the buffer is visiting that file. The copy in the buffer is what
58 you modify with editing commands. Such changes to the buffer do not
59 change the file; therefore, to make the changes permanent, you must
60 @dfn{save} the buffer, which means copying the altered buffer contents
63 In spite of the distinction between files and buffers, people often
64 refer to a file when they mean a buffer and vice-versa. Indeed, we say,
65 ``I am editing a file,'' rather than, ``I am editing a buffer that I
66 will soon save as a file of the same name.'' Humans do not usually need
67 to make the distinction explicit. When dealing with a computer program,
68 however, it is good to keep the distinction in mind.
71 * Visiting Functions:: The usual interface functions for visiting.
72 * Subroutines of Visiting:: Lower-level subroutines that they use.
76 @node Visiting Functions
77 @subsection Functions for Visiting Files
79 This section describes the functions normally used to visit files.
80 For historical reasons, these functions have names starting with
81 @samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for
82 functions and variables that access the visited file name of a buffer or
83 that find an existing buffer by its visited file name.
85 In a Lisp program, if you want to look at the contents of a file but
86 not alter it, the fastest way is to use @code{insert-file-contents} in a
87 temporary buffer. Visiting the file is not necessary and takes longer.
88 @xref{Reading from Files}.
90 @deffn Command find-file filename
91 This command selects a buffer visiting the file @var{filename},
92 using an existing buffer if there is one, and otherwise creating a
93 new buffer and reading the file into it. It also returns that buffer.
95 The body of the @code{find-file} function is very simple and looks
99 (switch-to-buffer (find-file-noselect filename))
103 (See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
105 When @code{find-file} is called interactively, it prompts for
106 @var{filename} in the minibuffer.
109 @defun find-file-noselect filename &optional nowarn
110 This function is the guts of all the file-visiting functions. It finds
111 or creates a buffer visiting the file @var{filename}, and returns it.
112 It uses an existing buffer if there is one, and otherwise creates a new
113 buffer and reads the file into it. You may make the buffer current or
114 display it in a window if you wish, but this function does not do so.
116 When @code{find-file-noselect} uses an existing buffer, it first
117 verifies that the file has not changed since it was last visited or
118 saved in that buffer. If the file has changed, then this function asks
119 the user whether to reread the changed file. If the user says
120 @samp{yes}, any changes previously made in the buffer are lost.
122 If @code{find-file-noselect} needs to create a buffer, and there is no
123 file named @var{filename}, it displays the message @samp{New file} in
124 the echo area, and leaves the buffer empty.
126 @c SXEmacs+XEmacs feature
127 If @var{nowarn} is non-@code{nil}, various warnings that SXEmacs normally
128 gives (e.g. if another buffer is already visiting @var{filename} but
129 @var{filename} has been removed from disk since that buffer was created)
132 The @code{find-file-noselect} function calls @code{after-find-file}
133 after reading the file (@pxref{Subroutines of Visiting}). That function
134 sets the buffer major mode, parses local variables, warns the user if
135 there exists an auto-save file more recent than the file just visited,
136 and finishes by running the functions in @code{find-file-hooks}.
138 The @code{find-file-noselect} function returns the buffer that is
139 visiting the file @var{filename}.
143 (find-file-noselect "/etc/fstab")
144 @result{} #<buffer fstab>
149 @deffn Command find-file-other-window filename
150 This command selects a buffer visiting the file @var{filename}, but
151 does so in a window other than the selected window. It may use another
152 existing window or split a window; see @ref{Displaying Buffers}.
154 When this command is called interactively, it prompts for
158 @deffn Command find-file-read-only filename
159 This command selects a buffer visiting the file @var{filename}, like
160 @code{find-file}, but it marks the buffer as read-only. @xref{Read Only
161 Buffers}, for related functions and variables.
163 When this command is called interactively, it prompts for
167 @deffn Command view-file filename &optional other-window-p
168 This command visits @var{filename} in View mode, and displays it in a
169 recursive edit, returning to the previous buffer when done. View mode
170 is a mode that allows you to skim rapidly through the file but does not
171 let you modify it. Entering View mode runs the normal hook
172 @code{view-mode-hook}. @xref{Hooks}.
174 When @code{view-file} is called interactively, it prompts for
177 With non-@code{nil} prefix arg @var{other-window-p}, visit @var{filename}
181 @defvar find-file-hooks
182 The value of this variable is a list of functions to be called after a
183 file is visited. The file's local-variables specification (if any) will
184 have been processed before the hooks are run. The buffer visiting the
185 file is current when the hook functions are run.
187 This variable works just like a normal hook, but we think that renaming
188 it would not be advisable.
191 @defvar find-file-not-found-hooks
192 The value of this variable is a list of functions to be called when
193 @code{find-file} or @code{find-file-noselect} is passed a nonexistent
194 file name. @code{find-file-noselect} calls these functions as soon as
195 it detects a nonexistent file. It calls them in the order of the list,
196 until one of them returns non-@code{nil}. @code{buffer-file-name} is
199 This is not a normal hook because the values of the functions are
200 used and they may not all be called.
204 @node Subroutines of Visiting
205 @subsection Subroutines of Visiting
207 The @code{find-file-noselect} function uses the
208 @code{create-file-buffer} and @code{after-find-file} functions as
209 subroutines. Sometimes it is useful to call them directly.
211 @defun create-file-buffer filename
212 This function creates a suitably named buffer for visiting
213 @var{filename}, and returns it. It uses @var{filename} (sans directory)
214 as the name if that name is free; otherwise, it appends a string such as
215 @samp{<2>} to get an unused name. See also @ref{Creating Buffers}.
217 @strong{Please note:} @code{create-file-buffer} does @emph{not}
218 associate the new buffer with a file and does not select the buffer.
219 It also does not use the default major mode.
223 (create-file-buffer "foo")
224 @result{} #<buffer foo>
227 (create-file-buffer "foo")
228 @result{} #<buffer foo<2>>
231 (create-file-buffer "foo")
232 @result{} #<buffer foo<3>>
236 This function is used by @code{find-file-noselect}.
237 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
240 @defun after-find-file &optional error warn noauto
241 This function sets the buffer major mode, and parses local variables
242 (@pxref{Auto Major Mode}). It is called by @code{find-file-noselect}
243 and by the default revert function (@pxref{Reverting}).
245 @cindex new file message
246 @cindex file open error
247 If reading the file got an error because the file does not exist, but
248 its directory does exist, the caller should pass a non-@code{nil} value
249 for @var{error}. In that case, @code{after-find-file} issues a warning:
250 @samp{(New File)}. For more serious errors, the caller should usually not
251 call @code{after-find-file}.
253 If @var{warn} is non-@code{nil}, then this function issues a warning
254 if an auto-save file exists and is more recent than the visited file.
256 @c SXEmacs+XEmacs feature
257 If @var{noauto} is non-@code{nil}, then this function does not turn
258 on auto-save mode; otherwise, it does.
260 The last thing @code{after-find-file} does is call all the functions
261 in @code{find-file-hooks}.
266 @section Saving Buffers
268 When you edit a file in SXEmacs, you are actually working on a buffer
269 that is visiting that file---that is, the contents of the file are
270 copied into the buffer and the copy is what you edit. Changes to the
271 buffer do not change the file until you @dfn{save} the buffer, which
272 means copying the contents of the buffer into the file.
274 @deffn Command save-buffer &optional backup-option
275 This function saves the contents of the current buffer in its visited
276 file if the buffer has been modified since it was last visited or saved.
277 Otherwise it does nothing.
279 @code{save-buffer} is responsible for making backup files. Normally,
280 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
281 file only if this is the first save since visiting the file. Other
282 values for @var{backup-option} request the making of backup files in
287 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
288 @code{save-buffer} function marks this version of the file to be
289 backed up when the buffer is next saved.
292 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
293 @code{save-buffer} function unconditionally backs up the previous
294 version of the file before saving it.
298 @deffn Command save-some-buffers &optional save-silently-p exiting
299 This command saves some modified file-visiting buffers. Normally it
300 asks the user about each buffer. But if @var{save-silently-p} is
301 non-@code{nil}, it saves all the file-visiting buffers without querying
304 The optional @var{exiting} argument, if non-@code{nil}, requests this
305 function to offer also to save certain other buffers that are not
306 visiting files. These are buffers that have a non-@code{nil} local
307 value of @code{buffer-offer-save}. (A user who says yes to saving one
308 of these is asked to specify a file name to use.) The
309 @code{save-buffers-kill-emacs} function passes a non-@code{nil} value
313 @defvar buffer-offer-save
314 When this variable is non-@code{nil} in a buffer, SXEmacs offers to save
315 the buffer on exit even if the buffer is not visiting a file. The
316 variable is automatically local in all buffers. Normally, Mail mode
317 (used for editing outgoing mail) sets this to @code{t}.
320 @deffn Command write-file filename
321 This function writes the current buffer into file @var{filename}, makes
322 the buffer visit that file, and marks it not modified. Then it renames
323 the buffer based on @var{filename}, appending a string like @samp{<2>}
324 if necessary to make a unique buffer name. It does most of this work by
325 calling @code{set-visited-file-name} and @code{save-buffer}.
328 @defvar write-file-hooks
329 The value of this variable is a list of functions to be called before
330 writing out a buffer to its visited file. If one of them returns
331 non-@code{nil}, the file is considered already written and the rest of
332 the functions are not called, nor is the usual code for writing the file
335 If a function in @code{write-file-hooks} returns non-@code{nil}, it
336 is responsible for making a backup file (if that is appropriate).
337 To do so, execute the following code:
340 (or buffer-backed-up (backup-buffer))
343 You might wish to save the file modes value returned by
344 @code{backup-buffer} and use that to set the mode bits of the file that
345 you write. This is what @code{save-buffer} normally does.
347 Even though this is not a normal hook, you can use @code{add-hook} and
348 @code{remove-hook} to manipulate the list. @xref{Hooks}.
352 @defvar local-write-file-hooks
353 This works just like @code{write-file-hooks}, but it is intended
354 to be made local to particular buffers. It's not a good idea to make
355 @code{write-file-hooks} local to a buffer---use this variable instead.
357 The variable is marked as a permanent local, so that changing the major
358 mode does not alter a buffer-local value. This is convenient for
359 packages that read ``file'' contents in special ways, and set up hooks
360 to save the data in a corresponding way.
364 @defvar write-contents-hooks
365 This works just like @code{write-file-hooks}, but it is intended for
366 hooks that pertain to the contents of the file, as opposed to hooks that
367 pertain to where the file came from. Such hooks are usually set up by
368 major modes, as buffer-local bindings for this variable. Switching to a
369 new major mode always resets this variable.
373 @defvar after-save-hook
374 This normal hook runs after a buffer has been saved in its visited file.
377 @defvar file-precious-flag
378 If this variable is non-@code{nil}, then @code{save-buffer} protects
379 against I/O errors while saving by writing the new file to a temporary
380 name instead of the name it is supposed to have, and then renaming it to
381 the intended name after it is clear there are no errors. This procedure
382 prevents problems such as a lack of disk space from resulting in an
385 As a side effect, backups are necessarily made by copying. @xref{Rename
386 or Copy}. Yet, at the same time, saving a precious file always breaks
387 all hard links between the file you save and other file names.
389 Some modes set this variable non-@code{nil} locally in particular
393 @defopt require-final-newline
394 This variable determines whether files may be written out that do
395 @emph{not} end with a newline. If the value of the variable is
396 @code{t}, then @code{save-buffer} silently adds a newline at the end of
397 the file whenever the buffer being saved does not already end in one.
398 If the value of the variable is non-@code{nil}, but not @code{t}, then
399 @code{save-buffer} asks the user whether to add a newline each time the
402 If the value of the variable is @code{nil}, then @code{save-buffer}
403 doesn't add newlines at all. @code{nil} is the default value, but a few
404 major modes set it to @code{t} in particular buffers.
408 @node Reading from Files
409 @section Reading from Files
411 You can copy a file from the disk and insert it into a buffer
412 using the @code{insert-file-contents} function. Don't use the user-level
413 command @code{insert-file} in a Lisp program, as that sets the mark.
415 @defun insert-file-contents filename &optional visit start end replace
416 This function inserts the contents of file @var{filename} into the
417 current buffer after point. It returns a list of the absolute file name
418 and the length of the data inserted. An error is signaled if
419 @var{filename} is not the name of a file that can be read.
421 The function @code{insert-file-contents} checks the file contents
422 against the defined file formats, and converts the file contents if
423 appropriate. @xref{Format Conversion}. It also calls the functions in
424 the list @code{after-insert-file-functions}; see @ref{Saving
427 If @var{visit} is non-@code{nil}, this function additionally marks the
428 buffer as unmodified and sets up various fields in the buffer so that it
429 is visiting the file @var{filename}: these include the buffer's visited
430 file name and its last save file modtime. This feature is used by
431 @code{find-file-noselect} and you probably should not use it yourself.
433 If @var{start} and @var{end} are non-@code{nil}, they should be integers
434 specifying the portion of the file to insert. In this case, @var{visit}
435 must be @code{nil}. For example,
438 (insert-file-contents filename nil 0 500)
442 inserts the first 500 characters of a file.
444 If the argument @var{replace} is non-@code{nil}, it means to replace the
445 contents of the buffer (actually, just the accessible portion) with the
446 contents of the file. This is better than simply deleting the buffer
447 contents and inserting the whole file, because (1) it preserves some
448 marker positions and (2) it puts less data in the undo list.
451 If you want to pass a file name to another process so that another
452 program can read the file, use the function @code{file-local-copy}; see
453 @ref{Magic File Names}.
456 @node Writing to Files
457 @section Writing to Files
459 You can write the contents of a buffer, or part of a buffer, directly
460 to a file on disk using the @code{append-to-file} and
461 @code{write-region} functions. Don't use these functions to write to
462 files that are being visited; that could cause confusion in the
463 mechanisms for visiting.
465 @deffn Command append-to-file start end filename
466 This function appends the contents of the region delimited by
467 @var{start} and @var{end} in the current buffer to the end of file
468 @var{filename}. If that file does not exist, it is created. If that
469 file exists it is overwritten. This function returns @code{nil}.
471 An error is signaled if @var{filename} specifies a nonwritable file,
472 or a nonexistent file in a directory where files cannot be created.
475 @deffn Command write-region start end filename &optional append visit
476 This function writes the region delimited by @var{start} and @var{end}
477 in the current buffer into the file specified by @var{filename}.
480 If @var{start} is a string, then @code{write-region} writes or appends
481 that string, rather than text from the buffer.
483 If @var{append} is non-@code{nil}, then the specified text is appended
484 to the existing file contents (if any).
486 If @var{visit} is @code{t}, then SXEmacs establishes an association
487 between the buffer and the file: the buffer is then visiting that file.
488 It also sets the last file modification time for the current buffer to
489 @var{filename}'s modtime, and marks the buffer as not modified. This
490 feature is used by @code{save-buffer}, but you probably should not use
494 If @var{visit} is a string, it specifies the file name to visit. This
495 way, you can write the data to one file (@var{filename}) while recording
496 the buffer as visiting another file (@var{visit}). The argument
497 @var{visit} is used in the echo area message and also for file locking;
498 @var{visit} is stored in @code{buffer-file-name}. This feature is used
499 to implement @code{file-precious-flag}; don't use it yourself unless you
500 really know what you're doing.
502 The function @code{write-region} converts the data which it writes to
503 the appropriate file formats specified by @code{buffer-file-format}.
504 @xref{Format Conversion}. It also calls the functions in the list
505 @code{write-region-annotate-functions}; see @ref{Saving Properties}.
507 Normally, @code{write-region} displays a message @samp{Wrote file
508 @var{filename}} in the echo area. If @var{visit} is neither @code{t}
509 nor @code{nil} nor a string, then this message is inhibited. This
510 feature is useful for programs that use files for internal purposes,
511 files that the user does not need to know about.
519 When two users edit the same file at the same time, they are likely to
520 interfere with each other. SXEmacs tries to prevent this situation from
521 arising by recording a @dfn{file lock} when a file is being modified.
522 SXEmacs can then detect the first attempt to modify a buffer visiting a
523 file that is locked by another SXEmacs process, and ask the user what to do.
525 File locks do not work properly when multiple machines can share
526 file systems, such as with NFS or AFS. Perhaps a better file locking system
527 will be implemented in the future. When file locks do not work, it is
528 possible for two users to make changes simultaneously, but SXEmacs can
529 still warn the user who saves second. Also, the detection of
530 modification of a buffer visiting a file changed on disk catches some
531 cases of simultaneous editing; see @ref{Modification Time}.
533 @c Not optional in FSF Emacs 19
534 @defun file-locked-p &optional filename
535 This function returns @code{nil} if the file @var{filename} is not
536 locked by this SXEmacs process. It returns @code{t} if it is locked by
537 this SXEmacs, and it returns the name of the user who has locked it if it
538 is locked by someone else.
542 (file-locked-p "foo")
548 @defun lock-buffer &optional filename
549 This function locks the file @var{filename}, if the current buffer is
550 modified. The argument @var{filename} defaults to the current buffer's
551 visited file. Nothing is done if the current buffer is not visiting a
552 file, or is not modified.
556 This function unlocks the file being visited in the current buffer,
557 if the buffer is modified. If the buffer is not modified, then
558 the file should not be locked, so this function does nothing. It also
559 does nothing if the current buffer is not visiting a file.
562 @defun ask-user-about-lock filename other-user
563 This function is called when the user tries to modify @var{filename},
564 but it is locked by another user named @var{other-user}. The value it
565 returns determines what happens next:
569 A value of @code{t} says to grab the lock on the file. Then
570 this user may edit the file and @var{other-user} loses the lock.
573 A value of @code{nil} says to ignore the lock and let this
574 user edit the file anyway.
578 This function may instead signal a @code{file-locked} error, in which
579 case the change that the user was about to make does not take place.
581 The error message for this error looks like this:
584 @error{} File is locked: @var{filename} @var{other-user}
588 where @var{filename} is the name of the file and @var{other-user} is the
589 name of the user who has locked the file.
592 The default definition of this function asks the user to choose what
593 to do. If you wish, you can replace the @code{ask-user-about-lock}
594 function with your own version that decides in another way. The code
595 for its usual definition is in @file{userlock.el}.
599 @node Information about Files
600 @section Information about Files
602 The functions described in this section all operate on strings that
603 designate file names. All the functions have names that begin with the
604 word @samp{file}. These functions all return information about actual
605 files or directories, so their arguments must all exist as actual files
606 or directories unless otherwise noted.
609 * Testing Accessibility:: Is a given file readable? Writable?
610 * Kinds of Files:: Is it a directory? A symbolic link?
611 * Truenames:: Eliminating symbolic links from a file name.
612 * File Attributes:: How large is it? Any other names? Etc.
616 @node Testing Accessibility
617 @subsection Testing Accessibility
618 @cindex accessibility of a file
619 @cindex file accessibility
621 These functions test for permission to access a file in specific ways.
623 @defun file-exists-p filename
624 This function returns @code{t} if a file named @var{filename} appears
625 to exist. This does not mean you can necessarily read the file, only
626 that you can find out its attributes. On Unix, this is true if the
627 file exists and you have execute permission on the containing
628 directories, regardless of the protection of the file itself.
630 If the file does not exist, or if fascist access control policies
631 prevent you from finding the attributes of the file, this function
635 @defun file-readable-p filename
636 This function returns @code{t} if a file named @var{filename} exists
637 and you can read it. It returns @code{nil} otherwise.
641 (file-readable-p "files.texi")
645 (file-exists-p "/usr/spool/mqueue")
649 (file-readable-p "/usr/spool/mqueue")
656 @defun file-executable-p filename
657 This function returns @code{t} if a file named @var{filename} exists and
658 you can execute it. It returns @code{nil} otherwise. If the file is a
659 directory, execute permission means you can check the existence and
660 attributes of files inside the directory, and open those files if their
664 @defun file-writable-p filename
665 This function returns @code{t} if the file @var{filename} can be written
666 or created by you, and @code{nil} otherwise. A file is writable if the
667 file exists and you can write it. It is creatable if it does not exist,
668 but the specified directory does exist and you can write in that
671 In the third example below, @file{foo} is not writable because the
672 parent directory does not exist, even though the user could create such
677 (file-writable-p "~/foo")
681 (file-writable-p "/foo")
685 (file-writable-p "~/no-such-dir/foo")
692 @defun file-accessible-directory-p dirname
693 This function returns @code{t} if you have permission to open existing
694 files in the directory whose name as a file is @var{dirname}; otherwise
695 (or if there is no such directory), it returns @code{nil}. The value
696 of @var{dirname} may be either a directory name or the file name of a
699 Example: after the following,
702 (file-accessible-directory-p "/foo")
707 we can deduce that any attempt to read a file in @file{/foo/} will
711 @defun file-ownership-preserved-p filename
712 This function returns @code{t} if deleting the file @var{filename} and
713 then creating it anew would keep the file's owner unchanged.
716 @defun file-newer-than-file-p filename1 filename2
718 @cindex file modification time
719 This function returns @code{t} if the file @var{filename1} is
720 newer than file @var{filename2}. If @var{filename1} does not
721 exist, it returns @code{nil}. If @var{filename2} does not exist,
724 In the following example, assume that the file @file{aug-19} was written
725 on the 19th, @file{aug-20} was written on the 20th, and the file
726 @file{no-file} doesn't exist at all.
730 (file-newer-than-file-p "aug-19" "aug-20")
734 (file-newer-than-file-p "aug-20" "aug-19")
738 (file-newer-than-file-p "aug-19" "no-file")
742 (file-newer-than-file-p "no-file" "aug-19")
747 You can use @code{file-attributes} to get a file's last modification
748 time as a list of two numbers. @xref{File Attributes}.
753 @subsection Distinguishing Kinds of Files
755 This section describes how to distinguish various kinds of files, such
756 as directories, symbolic links, and ordinary files.
758 @defun file-symlink-p filename
759 @cindex file symbolic links
760 If the file @var{filename} is a symbolic link, the @code{file-symlink-p}
761 function returns the file name to which it is linked. This may be the
762 name of a text file, a directory, or even another symbolic link, or it
763 may be a nonexistent file name.
765 If the file @var{filename} is not a symbolic link (or there is no such file),
766 @code{file-symlink-p} returns @code{nil}.
770 (file-symlink-p "foo")
774 (file-symlink-p "sym-link")
778 (file-symlink-p "sym-link2")
782 (file-symlink-p "/bin")
787 @c !!! file-symlink-p: should show output of ls -l for comparison
790 @defun file-directory-p filename
791 This function returns @code{t} if @var{filename} is the name of an
792 existing directory, @code{nil} otherwise.
796 (file-directory-p "~rms")
800 (file-directory-p "~rms/lewis/files.texi")
804 (file-directory-p "~rms/lewis/no-such-file")
808 (file-directory-p "$HOME")
813 (substitute-in-file-name "$HOME"))
819 @defun file-regular-p filename
820 This function returns @code{t} if the file @var{filename} exists and is
821 a regular file (not a directory, symbolic link, named pipe, terminal, or
827 @subsection Truenames
828 @cindex truename (of file)
831 The @dfn{truename} of a file is the name that you get by following
832 symbolic links until none remain, then expanding to get rid of @samp{.}
833 and @samp{..} as components. Strictly speaking, a file need not have a
834 unique truename; the number of distinct truenames a file has is equal to
835 the number of hard links to the file. However, truenames are useful
836 because they eliminate symbolic links as a cause of name variation.
838 @defun file-truename filename &optional default
839 The function @code{file-truename} returns the true name of the file
840 @var{filename}. This is the name that you get by following symbolic
841 links until none remain.
843 @c SXEmacs+XEmacs allow relative filenames
844 If the filename is relative, @var{default} is the directory to start
845 with. If @var{default} is @code{nil} or missing, the current buffer's
846 value of @code{default-directory} is used.
849 @xref{Buffer File Name}, for related information.
852 @node File Attributes
853 @subsection Other Information about Files
855 This section describes the functions for getting detailed information
856 about a file, other than its contents. This information includes the
857 mode bits that control access permission, the owner and group numbers,
858 the number of names, the inode number, the size, and the times of access
861 @defun file-modes filename
863 @cindex file attributes
864 This function returns the mode bits of @var{filename}, as an integer.
865 The mode bits are also called the file permissions, and they specify
866 access control in the usual Unix fashion. If the low-order bit is 1,
867 then the file is executable by all users, if the second-lowest-order bit
868 is 1, then the file is writable by all users, etc.
870 The highest value returnable is 4095 (7777 octal), meaning that
871 everyone has read, write, and execute permission, that the @sc{suid} bit
872 is set for both others and group, and that the sticky bit is set.
876 (file-modes "~/junk/diffs")
877 @result{} 492 ; @r{Decimal integer.}
881 @result{} "754" ; @r{Convert to octal.}
885 (set-file-modes "~/junk/diffs" 438)
891 @result{} "666" ; @r{Convert to octal.}
896 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
901 @defun file-nlinks filename
902 This functions returns the number of names (i.e., hard links) that
903 file @var{filename} has. If the file does not exist, then this function
904 returns @code{nil}. Note that symbolic links have no effect on this
905 function, because they are not considered to be names of the files they
911 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
912 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
920 (file-nlinks "doesnt-exist")
926 @defun file-attributes filename
927 This function returns a list of attributes of file @var{filename}. If
928 the specified file cannot be opened, it returns @code{nil}.
930 The elements of the list, in order, are:
934 @code{t} for a directory, a string for a symbolic link (the name
935 linked to), or @code{nil} for a text file.
937 @c Wordy so as to prevent an overfull hbox. --rjc 15mar92
939 The number of names the file has. Alternate names, also known as hard
940 links, can be created by using the @code{add-name-to-file} function
941 (@pxref{Changing File Attributes}).
950 The time of last access, as a list of two integers.
951 The first integer has the high-order 16 bits of time,
952 the second has the low 16 bits. (This is similar to the
953 value of @code{current-time}; see @ref{Time of Day}.)
956 The time of last modification as a list of two integers (as above).
959 The time of last status change as a list of two integers (as above).
962 The size of the file in bytes.
965 The file's modes, as a string of ten letters or dashes,
969 @code{t} if the file's @sc{gid} would change if file were
970 deleted and recreated; @code{nil} otherwise.
973 The file's inode number.
976 The file system number of the file system that the file is in. This
977 element and the file's inode number together give enough information to
978 distinguish any two files on the system---no two files can have the same
979 values for both of these numbers.
982 For example, here are the file attributes for @file{files.texi}:
986 (file-attributes "files.texi")
1003 and here is how the result is interpreted:
1007 is neither a directory nor a symbolic link.
1010 has only one name (the name @file{files.texi} in the current default
1014 is owned by the user with @sc{uid} 2235.
1017 is in the group with @sc{gid} 75.
1020 was last accessed on Aug 19 00:09. Use @code{format-time-string} to
1021 ! convert this number into a time string. @xref{Time Conversion}.
1024 was last modified on Aug 19 00:09.
1027 last had its inode changed on Aug 19 00:09.
1030 is 14906 characters long.
1033 has a mode of read and write access for the owner, group, and world.
1036 would retain the same @sc{gid} if it were recreated.
1039 has an inode number of 129500.
1041 is on file system number -32252.
1046 @node Changing File Attributes
1047 @section Changing File Names and Attributes
1048 @cindex renaming files
1049 @cindex copying files
1050 @cindex deleting files
1051 @cindex linking files
1052 @cindex setting modes of files
1054 The functions in this section rename, copy, delete, link, and set the
1057 In the functions that have arguments @var{newname} and
1058 @var{ok-if-already-exists}, if a file by the name of @var{newname}
1059 already exists, the actions taken depend on the value of
1060 @var{ok-if-already-exists}:
1064 Signal a @code{file-already-exists} error if
1065 @var{ok-if-already-exists} is @code{nil}.
1068 Request confirmation if @var{ok-if-already-exists} is a number. This is
1069 what happens when the function is invoked interactively.
1072 Replace the old file without confirmation if @var{ok-if-already-exists}
1076 @deffn Command add-name-to-file filename newname &optional ok-if-already-exists
1077 @cindex file with multiple names
1078 @cindex file hard link
1079 This function gives the file named @var{filename} the additional name
1080 @var{newname}. This means that @var{newname} becomes a new ``hard
1081 link'' to @var{filename}. Both these arguments must be strings.
1083 In the first part of the following example, we list two files,
1084 @file{foo} and @file{foo3}.
1089 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
1090 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
1094 Then we evaluate the form @code{(add-name-to-file "~/lewis/foo"
1095 "~/lewis/foo2")}. Again we list the files. This shows two names,
1096 @file{foo} and @file{foo2}.
1100 (add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
1106 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
1107 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
1108 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
1112 @c !!! Check whether this set of examples is consistent. --rjc 15mar92
1113 Finally, we evaluate the following:
1116 (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
1120 and list the files again. Now there are three names
1121 for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old
1122 contents of @file{foo3} are lost.
1126 (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
1132 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
1133 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
1134 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
1138 This function is meaningless on non-Unix systems, where multiple names
1139 for one file are not allowed.
1141 See also @code{file-nlinks} in @ref{File Attributes}.
1144 @deffn Command rename-file filename newname &optional ok-if-already-exists
1145 This command renames the file @var{filename} as @var{newname}.
1147 If @var{filename} has additional names aside from @var{filename}, it
1148 continues to have those names. In fact, adding the name @var{newname}
1149 with @code{add-name-to-file} and then deleting @var{filename} has the
1150 same effect as renaming, aside from momentary intermediate states.
1152 In an interactive call, this function prompts for @var{filename} and
1153 @var{newname} in the minibuffer; also, it requests confirmation if
1154 @var{newname} already exists.
1157 @deffn Command copy-file filename newname &optional ok-if-already-exists time
1158 This command copies the file @var{filename} to @var{newname}. An
1159 error is signaled if @var{filename} does not exist.
1161 If @var{time} is non-@code{nil}, then this functions gives the new
1162 file the same last-modified time that the old one has. (This works on
1163 only some operating systems.)
1165 In an interactive call, this function prompts for @var{filename} and
1166 @var{newname} in the minibuffer; also, it requests confirmation if
1167 @var{newname} already exists.
1170 @deffn Command delete-file filename
1172 This command deletes the file @var{filename}, like the shell command
1173 @samp{rm @var{filename}}. If the file has multiple names, it continues
1174 to exist under the other names.
1176 A suitable kind of @code{file-error} error is signaled if the file
1177 does not exist, or is not deletable. On Unix, a file is deletable if
1178 its directory is writable.
1180 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
1183 @deffn Command make-symbolic-link filename newname &optional ok-if-already-exists
1185 @kindex file-already-exists
1186 This command makes a symbolic link to @var{filename}, named
1187 @var{newname}. This is like the shell command @samp{ln -s
1188 @var{filename} @var{newname}}.
1190 In an interactive call, this function prompts for @var{filename} and
1191 @var{newname} in the minibuffer; also, it requests confirmation if
1192 @var{newname} already exists.
1195 @defun set-file-modes filename mode
1196 This function sets mode bits of @var{filename} to @var{mode} (which must
1197 be an integer). Only the low 12 bits of @var{mode} are used.
1201 @defun set-default-file-modes mode
1202 This function sets the default file protection for new files created by
1203 SXEmacs and its subprocesses. Every file created with SXEmacs initially
1204 has this protection. On Unix, the default protection is the bitwise
1205 complement of the ``umask'' value.
1207 The argument @var{mode} must be an integer. Only the low 9 bits of
1208 @var{mode} are used.
1210 Saving a modified version of an existing file does not count as creating
1211 the file; it does not change the file's mode, and does not use the
1212 default file protection.
1215 @defun default-file-modes
1216 This function returns the current default protection value.
1224 Files are generally referred to by their names, in SXEmacs as elsewhere.
1225 File names in SXEmacs are represented as strings. The functions that
1226 operate on a file all expect a file name argument.
1228 In addition to operating on files themselves, SXEmacs Lisp programs
1229 often need to operate on the names; i.e., to take them apart and to use
1230 part of a name to construct related file names. This section describes
1231 how to manipulate file names.
1233 The functions in this section do not actually access files, so they
1234 can operate on file names that do not refer to an existing file or
1238 * File Name Components:: The directory part of a file name, and the rest.
1239 * Directory Names:: A directory's name as a directory
1240 is different from its name as a file.
1241 * Relative File Names:: Some file names are relative to a current directory.
1242 * File Name Expansion:: Converting relative file names to absolute ones.
1243 * Unique File Names:: Generating names for temporary files.
1244 * File Name Completion:: Finding the completions for a given file name.
1245 * User Name Completion:: Finding the completions for a given user name.
1249 @node File Name Components
1250 @subsection File Name Components
1251 @cindex directory part (of file name)
1252 @cindex nondirectory part (of file name)
1253 @cindex version number (in file name)
1255 The operating system groups files into directories. To specify a
1256 file, you must specify the directory and the file's name within that
1257 directory. Therefore, SXEmacs considers a file name as having two main
1258 parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
1259 (or @dfn{file name within the directory}). Either part may be empty.
1260 Concatenating these two parts reproduces the original file name.
1262 On Unix, the directory part is everything up to and including the last
1263 slash; the nondirectory part is the rest.
1265 For some purposes, the nondirectory part is further subdivided into
1266 the name proper and the @dfn{version number}. On Unix, only backup
1267 files have version numbers in their names.
1269 @defun file-name-directory filename
1270 This function returns the directory part of @var{filename} (or
1271 @code{nil} if @var{filename} does not include a directory part). On
1272 Unix, the function returns a string ending in a slash.
1276 (file-name-directory "lewis/foo") ; @r{Unix example}
1280 (file-name-directory "foo") ; @r{Unix example}
1286 @defun file-name-nondirectory filename
1287 This function returns the nondirectory part of @var{filename}.
1291 (file-name-nondirectory "lewis/foo")
1295 (file-name-nondirectory "foo")
1301 @defun file-name-sans-versions filename &optional keep-backup-version
1302 This function returns @var{filename} without any file version numbers,
1303 backup version numbers, or trailing tildes.
1306 If @var{keep-backup-version} is non-@code{nil}, we do not remove backup
1307 version numbers, only true file version numbers.
1311 (file-name-sans-versions "~rms/foo.~1~")
1312 @result{} "~rms/foo"
1315 (file-name-sans-versions "~rms/foo~")
1316 @result{} "~rms/foo"
1319 (file-name-sans-versions "~rms/foo")
1320 @result{} "~rms/foo"
1325 @defun file-name-sans-extension filename
1326 This function returns @var{filename} minus its ``extension,'' if any.
1327 The extension, in a file name, is the part that starts with the last
1328 @samp{.} in the last name component. For example,
1331 (file-name-sans-extension "foo.lose.c")
1332 @result{} "foo.lose"
1333 (file-name-sans-extension "big.hack/foo")
1334 @result{} "big.hack/foo"
1339 @node Directory Names
1340 @subsection Directory Names
1341 @cindex directory name
1342 @cindex file name of directory
1344 A @dfn{directory name} is the name of a directory. A directory is a
1345 kind of file, and it has a file name, which is related to the directory
1346 name but not identical to it. This is not quite the same as the usual
1347 Unix terminology. These two different names for the same entity are
1348 related by a syntactic transformation. On Unix, this is simple: a
1349 directory name ends in a slash, whereas the directory's name as a file
1352 The difference between a directory name and its name as a file is
1353 subtle but crucial. When a SXEmacs variable or function argument is
1354 described as being a directory name, a file name of a directory is not
1357 The following two functions convert between directory names and file
1358 names. They do nothing special with environment variable substitutions
1359 such as @samp{$HOME}, and the constructs @samp{~}, and @samp{..}.
1361 @defun file-name-as-directory filename
1362 This function returns a string representing @var{filename} in a form
1363 that the operating system will interpret as the name of a directory. In
1364 Unix, this means appending a slash to the string.
1368 (file-name-as-directory "~rms/lewis")
1369 @result{} "~rms/lewis/"
1374 @defun directory-file-name dirname
1375 This function returns a string representing @var{dirname} in a form
1376 that the operating system will interpret as the name of a file. On
1377 Unix, this means removing a final slash from the string.
1381 (directory-file-name "~lewis/")
1387 @cindex directory name abbreviation
1388 Directory name abbreviations are useful for directories that are
1389 normally accessed through symbolic links. Sometimes the users recognize
1390 primarily the link's name as ``the name'' of the directory, and find it
1391 annoying to see the directory's ``real'' name. If you define the link
1392 name as an abbreviation for the ``real'' name, SXEmacs shows users the
1393 abbreviation instead.
1395 If you wish to convert a directory name to its abbreviation, use this
1398 @defun abbreviate-file-name filename &optional hack-homedir
1399 This function applies abbreviations from @code{directory-abbrev-alist}
1400 to its argument, and substitutes @samp{~} for the user's home
1404 If @var{hack-homedir} is non-@code{nil}, then this also substitutes
1405 @samp{~} for the user's home directory.
1409 @defvar directory-abbrev-alist
1410 The variable @code{directory-abbrev-alist} contains an alist of
1411 abbreviations to use for file directories. Each element has the form
1412 @code{(@var{from} . @var{to})}, and says to replace @var{from} with
1413 @var{to} when it appears in a directory name. The @var{from} string is
1414 actually a regular expression; it should always start with @samp{^}.
1415 The function @code{abbreviate-file-name} performs these substitutions.
1417 You can set this variable in @file{site-init.el} to describe the
1418 abbreviations appropriate for your site.
1420 Here's an example, from a system on which file system @file{/home/fsf}
1421 and so on are normally accessed through symbolic links named @file{/fsf}
1425 (("^/home/fsf" . "/fsf")
1426 ("^/home/gp" . "/gp")
1427 ("^/home/gd" . "/gd"))
1431 To convert a directory name to its abbreviation, use this
1434 @defun abbreviate-file-name dirname
1435 This function applies abbreviations from @code{directory-abbrev-alist}
1436 to its argument, and substitutes @samp{~} for the user's home
1441 @node Relative File Names
1442 @subsection Absolute and Relative File Names
1443 @cindex absolute file name
1444 @cindex relative file name
1446 All the directories in the file system form a tree starting at the
1447 root directory. A file name can specify all the directory names
1448 starting from the root of the tree; then it is called an @dfn{absolute}
1449 file name. Or it can specify the position of the file in the tree
1450 relative to a default directory; then it is called a @dfn{relative}
1451 file name. On Unix, an absolute file name starts with a slash or a
1452 tilde (@samp{~}), and a relative one does not.
1454 @defun file-name-absolute-p filename
1455 This function returns @code{t} if file @var{filename} is an absolute
1456 file name, @code{nil} otherwise.
1460 (file-name-absolute-p "~rms/foo")
1464 (file-name-absolute-p "rms/foo")
1468 (file-name-absolute-p "/user/rms/foo")
1475 @node File Name Expansion
1476 @subsection Functions that Expand Filenames
1477 @cindex expansion of file names
1479 @dfn{Expansion} of a file name means converting a relative file name
1480 to an absolute one. Since this is done relative to a default directory,
1481 you must specify the default directory name as well as the file name to
1482 be expanded. Expansion also simplifies file names by eliminating
1483 redundancies such as @file{./} and @file{@var{name}/../}.
1485 @defun expand-file-name filename &optional directory
1486 This function converts @var{filename} to an absolute file name. If
1487 @var{directory} is supplied, it is the directory to start with if
1488 @var{filename} is relative. (The value of @var{directory} should itself
1489 be an absolute directory name; it may start with @samp{~}.)
1490 Otherwise, the current buffer's value of @code{default-directory} is
1495 (expand-file-name "foo")
1496 @result{} "/xcssun/users/rms/lewis/foo"
1499 (expand-file-name "../foo")
1500 @result{} "/xcssun/users/rms/foo"
1503 (expand-file-name "foo" "/usr/spool/")
1504 @result{} "/usr/spool/foo"
1507 (expand-file-name "$HOME/foo")
1508 @result{} "/xcssun/users/rms/lewis/$HOME/foo"
1512 Filenames containing @samp{.} or @samp{..} are simplified to their
1517 (expand-file-name "bar/../foo")
1518 @result{} "/xcssun/users/rms/lewis/foo"
1522 @samp{~/} at the beginning is expanded into the user's home directory.
1523 A @samp{/} or @samp{~} following a @samp{/}.
1525 Note that @code{expand-file-name} does @emph{not} expand environment
1526 variables; only @code{substitute-in-file-name} does that.
1530 @defun file-relative-name filename &optional directory
1531 This function does the inverse of expansion---it tries to return a
1532 relative name that is equivalent to @var{filename} when interpreted
1533 relative to @var{directory}.
1536 If @var{directory} is @code{nil} or omitted, the value of
1537 @code{default-directory} is used.
1540 (file-relative-name "/foo/bar" "/foo/")
1542 (file-relative-name "/foo/bar" "/hack/")
1543 @result{} "../foo/bar")
1547 @defvar default-directory
1548 The value of this buffer-local variable is the default directory for the
1549 current buffer. It should be an absolute directory name; it may start
1550 with @samp{~}. This variable is local in every buffer.
1552 @code{expand-file-name} uses the default directory when its second
1553 argument is @code{nil}.
1555 On Unix systems, the value is always a string ending with a slash.
1560 @result{} "/user/lewis/manual/"
1565 @defun substitute-in-file-name filename
1566 This function replaces environment variable references in
1567 @var{filename} with the environment variable values. Following standard
1568 Unix shell syntax, @samp{$} is the prefix to substitute an environment
1571 The environment variable name is the series of alphanumeric characters
1572 (including underscores) that follow the @samp{$}. If the character following
1573 the @samp{$} is a @samp{@{}, then the variable name is everything up to the
1576 @c Wordy to avoid overfull hbox. --rjc 15mar92
1577 Here we assume that the environment variable @code{HOME}, which holds
1578 the user's home directory name, has value @samp{/xcssun/users/rms}.
1582 (substitute-in-file-name "$HOME/foo")
1583 @result{} "/xcssun/users/rms/foo"
1587 @c If a @samp{~} or a @samp{/} appears following a @samp{/}, after
1588 @c substitution, everything before the following @samp{/} is discarded:
1590 After substitution, a @samp{/} or @samp{~} following a @samp{/} is taken
1591 to be the start of an absolute file name that overrides what precedes
1592 it, so everything before that @samp{/} or @samp{~} is deleted. For
1597 (substitute-in-file-name "bar/~/foo")
1601 (substitute-in-file-name "/usr/local/$HOME/foo")
1602 @result{} "/xcssun/users/rms/foo"
1608 @node Unique File Names
1609 @subsection Generating Unique File Names
1611 Some programs need to write temporary files. Here is the usual way to
1612 construct a name for such a file:
1615 (make-temp-name (expand-file-name @var{name-of-application} (temp-directory)))
1619 Here we use @code{(temp-directory)} to specify a directory for temporary
1620 files---under Unix, it will normally evaluate to @file{"/tmp/"}. The
1621 job of @code{make-temp-name} is to prevent two different users or two
1622 different processes from trying to use the same name.
1624 @defun temp-directory
1625 This function returns the name of the directory to use for temporary
1626 files. Under Unix, this will be the value of @code{TMPDIR}, defaulting
1629 @c note to myself: check this
1630 Note: The @code{temp-directory} function does not exist under FSF Emacs.
1633 @defun make-temp-name prefix
1634 This function generates a temporary file name starting with
1635 @var{prefix}. The Emacs process number forms part of the result, so
1636 there is no danger of generating a name being used by another process.
1640 (make-temp-name "/tmp/foo")
1641 @result{} "/tmp/fooGaAQjC"
1645 In addition, this function makes an attempt to choose a name that does
1646 not specify an existing file. To make this work, @var{prefix} should be
1647 an absolute file name.
1649 To avoid confusion, each Lisp application should preferably use a unique
1650 @var{prefix} to @code{make-temp-name}.
1654 @node File Name Completion
1655 @subsection File Name Completion
1656 @cindex file name completion subroutines
1657 @cindex completion, file name
1659 This section describes low-level subroutines for completing a file
1660 name. For other completion functions, see @ref{Completion}.
1662 @defun file-name-all-completions partial-filename directory
1663 This function returns a list of all possible completions for files
1664 whose name starts with @var{partial-filename} in directory
1665 @var{directory}. The order of the completions is the order of the files
1666 in the directory, which is unpredictable and conveys no useful
1669 The argument @var{partial-filename} must be a file name containing no
1670 directory part and no slash. The current buffer's default directory is
1671 prepended to @var{directory}, if @var{directory} is not absolute.
1673 File names which end with any member of @code{completion-ignored-extensions}
1674 are not considered as possible completions for @var{partial-filename} unless
1675 there is no other possible completion. @code{completion-ignored-extensions}
1676 is not applied to the names of directories.
1678 In the following example, suppose that the current default directory,
1679 @file{~rms/lewis}, has five files whose names begin with @samp{f}:
1680 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
1681 @file{file.c.~2~}.@refill
1685 (file-name-all-completions "f" "")
1686 @result{} ("foo" "file~" "file.c.~2~"
1687 "file.c.~1~" "file.c")
1691 (file-name-all-completions "fo" "")
1697 @defun file-name-completion partial-filename directory
1698 This function completes the file name @var{partial-filename} in directory
1699 @var{directory}. It returns the longest prefix common to all file names
1700 in directory @var{directory} that start with @var{partial-filename}.
1702 If only one match exists and @var{partial-filename} matches it exactly, the
1703 function returns @code{t}. The function returns @code{nil} if directory
1704 @var{directory} contains no name starting with @var{partial-filename}.
1706 File names which end with any member of @code{completion-ignored-extensions}
1707 are not considered as possible completions for @var{partial-filename} unless
1708 there is no other possible completion. @code{completion-ignored-extensions}
1709 is not applied to the names of directories.
1711 In the following example, suppose that the current default directory
1712 has five files whose names begin with @samp{f}: @file{foo},
1713 @file{file~}, @file{file.c}, @file{file.c.~1~}, and
1714 @file{file.c.~2~}.@refill
1718 (file-name-completion "fi" "")
1723 (file-name-completion "file.c.~1" "")
1724 @result{} "file.c.~1~"
1728 (file-name-completion "file.c.~1~" "")
1733 (file-name-completion "file.c.~3" "")
1739 @defopt completion-ignored-extensions
1740 @code{file-name-completion} usually ignores file names that end in any
1741 string in this list. It does not ignore them when all the possible
1742 completions end in one of these suffixes or when a buffer showing all
1743 possible completions is displayed.@refill
1745 A typical value might look like this:
1749 completion-ignored-extensions
1750 @result{} (".o" ".elc" "~" ".dvi")
1756 @node User Name Completion
1757 @subsection User Name Completion
1758 @cindex user name completion subroutines
1759 @cindex completion, user name
1761 This section describes low-level subroutines for completing a user
1762 name. For other completion functions, see @ref{Completion}.
1764 @defun user-name-all-completions partial-username
1765 This function returns a list of all possible completions for a user name
1766 starting with @var{partial-username}. The order of the completions is
1767 unpredictable and conveys no useful information.
1769 The argument @var{partial-username} must be a partial user name
1770 containing no tilde character and no slash.
1773 @defun user-name-completion partial-username
1774 This function completes a user name from @var{partial-username}. It
1775 returns the longest prefix common to all user names that start with
1776 @var{partial-username}.
1778 If only one match exists and @var{partial-username} matches it exactly,
1779 the function returns @code{t}. The function returns @code{nil} if no
1780 user name starting with @var{partial-username} exists.
1783 @defun user-name-completion-1 partial-username
1784 This function completes the partial user name @var{partial-username},
1785 like @code{user-name-completion}, differing only in the return value.
1786 This function returns the cons of the completion returned by
1787 @code{user-name-completion}, and a boolean indicating whether that
1788 completion was unique.
1792 @node Contents of Directories
1793 @section Contents of Directories
1794 @cindex directory-oriented functions
1795 @cindex file names in directory
1797 A directory is a kind of file that contains other files entered under
1798 various names. Directories are a feature of the file system.
1800 SXEmacs can list the names of the files in a directory as a Lisp list,
1801 or display the names in a buffer using the @code{ls} shell command. In
1802 the latter case, it can optionally display information about each file,
1803 depending on the value of switches passed to the @code{ls} command.
1805 @defun directory-files directory &optional full-name match-regexp nosort files-only
1806 This function returns a list of the names of the files in the directory
1807 @var{directory}. By default, the list is in alphabetical order.
1809 If @var{full-name} is non-@code{nil}, the function returns the files'
1810 absolute file names. Otherwise, it returns just the names relative to
1811 the specified directory.
1813 If @var{match-regexp} is non-@code{nil}, this function returns only
1814 those file names that contain that regular expression---the other file
1815 names are discarded from the list.
1818 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
1819 the list, so you get the file names in no particular order. Use this if
1820 you want the utmost possible speed and don't care what order the files
1821 are processed in. If the order of processing is visible to the user,
1822 then the user will probably be happier if you do sort the names.
1825 If @var{files-only} is the symbol @code{t}, then only the ``files'' in
1826 the directory will be returned; subdirectories will be excluded. If
1827 @var{files-only} is not @code{nil} and not @code{t}, then only the
1828 subdirectories will be returned. Otherwise, if @var{files-only} is
1829 @code{nil} (the default) then both files and subdirectories will be
1834 (directory-files "~lewis")
1835 @result{} ("#foo#" "#foo.el#" "." ".."
1836 "dired-mods.el" "files.texi"
1841 An error is signaled if @var{directory} is not the name of a directory
1845 Moreover, there is a generalised function which also performs a
1846 recursive descent within a directory tree. This function is especially
1847 optimised for large recursion depths and has an outstanding
1850 @defun directory-files-recur directory &optional full match nosort files-only depth symlink_is_file
1851 Like @code{directory-files} but recursive and much faster.
1853 Optional argument @var{depth} (a positive integer) specifies the
1854 recursion depth, use @code{0} to emulate old @code{directory-files}.
1856 Optional argument @var{symlink_is_file} specifies whether symlinks
1857 should be resolved (which is the default behaviour) or whether
1858 they are treated as ordinary files (non-@code{nil}), in the latter
1859 case symlinks to directories are not recurred.
1864 (directory-files-recur "/sys/class/dvb")
1865 @result{} ("./dvb0.demux0" "./dvb0.demux0/dev" "./dvb0.demux0/uevent"
1866 "./dvb0.dvr0" "./dvb0.dvr0/dev" "./dvb0.dvr0/uevent"
1867 "./dvb0.frontend0" "./dvb0.frontend0/dev"
1868 "./dvb0.frontend0/uevent" "./dvb0.net0" "./dvb0.net0/dev"
1869 "./dvb0.net0/uevent")
1873 (directory-files-recur "/sys/class/dvb" t nil nil nil 0)
1874 @result{} ("/sys/class/dvb/dvb0.demux0" "/sys/class/dvb/dvb0.dvr0"
1875 "/sys/class/dvb/dvb0.frontend0" "/sys/class/dvb/dvb0.net0")
1880 @ignore @c Not in XEmacs
1881 @defun file-name-all-versions file dirname
1882 This function returns a list of all versions of the file named
1883 @var{file} in directory @var{dirname}.
1887 @defun insert-directory file switches &optional wildcard full-directory-p
1888 This function inserts (in the current buffer) a directory listing for
1889 directory @var{file}, formatted with @code{ls} according to
1890 @var{switches}. It leaves point after the inserted text.
1892 The argument @var{file} may be either a directory name or a file
1893 specification including wildcard characters. If @var{wildcard} is
1894 non-@code{nil}, that means treat @var{file} as a file specification with
1897 If @var{full-directory-p} is non-@code{nil}, that means @var{file} is a
1898 directory and switches do not contain @samp{-d}, so that the listing
1899 should show the full contents of the directory. (The @samp{-d} option
1900 to @code{ls} says to describe a directory itself rather than its
1903 This function works by running a directory listing program whose name is
1904 in the variable @code{insert-directory-program}. If @var{wildcard} is
1905 non-@code{nil}, it also runs the shell specified by
1906 @code{shell-file-name}, to expand the wildcards.
1909 @defvar insert-directory-program
1910 This variable's value is the program to run to generate a directory listing
1911 for the function @code{insert-directory}.
1915 @node Create/Delete Dirs
1916 @section Creating and Deleting Directories
1917 @c Emacs 19 features
1919 Most SXEmacs Lisp file-manipulation functions get errors when used on
1920 files that are directories. For example, you cannot delete a directory
1921 with @code{delete-file}. These special functions exist to create and
1924 @deffn Command make-directory dirname &optional parents
1925 This function creates a directory named @var{dirname}. Interactively,
1926 the default choice of directory to create is the current default
1927 directory for file names. That is useful when you have visited a file
1928 in a nonexistent directory.
1930 @c SXEmacs+XEmacs feature
1931 Non-interactively, optional argument @var{parents} says whether to
1932 create parent directories if they don't exist. (Interactively, this
1936 @deffn Command delete-directory dirname
1937 This function deletes the directory named @var{dirname}. The function
1938 @code{delete-file} does not work for files that are directories; you
1939 must use @code{delete-directory} in that case.
1943 @node Magic File Names
1944 @section Making Certain File Names ``Magic''
1945 @cindex magic file names
1948 You can implement special handling for certain file names. This is
1949 called making those names @dfn{magic}. You must supply a regular
1950 expression to define the class of names (all those that match the
1951 regular expression), plus a handler that implements all the primitive
1952 SXEmacs file operations for file names that do match.
1954 The variable @code{file-name-handler-alist} holds a list of handlers,
1955 together with regular expressions that determine when to apply each
1956 handler. Each element has this form:
1959 (@var{regexp} . @var{handler})
1963 All the SXEmacs primitives for file access and file name transformation
1964 check the given file name against @code{file-name-handler-alist}. If
1965 the file name matches @var{regexp}, the primitives handle that file by
1966 calling @var{handler}.
1968 The first argument given to @var{handler} is the name of the primitive;
1969 the remaining arguments are the arguments that were passed to that
1970 operation. (The first of these arguments is typically the file name
1971 itself.) For example, if you do this:
1974 (file-exists-p @var{filename})
1978 and @var{filename} has handler @var{handler}, then @var{handler} is
1982 (funcall @var{handler} 'file-exists-p @var{filename})
1985 Here are the operations that a magic file name handler gets to handle:
1988 @code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
1989 @code{delete-file},@*
1990 @code{diff-latest-backup-file},
1991 @code{directory-file-name},
1992 @code{directory-files},
1993 @code{dired-compress-file}, @code{dired-uncache},
1994 @code{expand-file-name},@*
1995 @code{file-accessible-directory-p},
1996 @code{file-attributes}, @code{file-directory-p},
1997 @code{file-executable-p}, @code{file-exists-p}, @code{file-local-copy},
1998 @code{file-modes}, @code{file-name-all-completions},
1999 @code{file-name-as-directory}, @code{file-name-completion},
2000 @code{file-name-directory}, @code{file-name-nondirectory},
2001 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
2002 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
2003 @code{file-truename}, @code{file-writable-p},
2004 @code{get-file-buffer},
2005 @code{insert-directory},
2006 @code{insert-file-contents}, @code{load}, @code{make-directory},
2007 @code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
2008 @code{set-visited-file-modtime}, @code{unhandled-file-name-directory},
2009 @code{verify-visited-file-modtime}, @code{write-region}.
2011 Handlers for @code{insert-file-contents} typically need to clear the
2012 buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
2013 @var{visit} argument is non-@code{nil}. This also has the effect of
2014 unlocking the buffer if it is locked.
2016 The handler function must handle all of the above operations, and
2017 possibly others to be added in the future. It need not implement all
2018 these operations itself---when it has nothing special to do for a
2019 certain operation, it can reinvoke the primitive, to handle the
2020 operation ``in the usual way''. It should always reinvoke the primitive
2021 for an operation it does not recognize. Here's one way to do this:
2024 (defun my-file-handler (operation &rest args)
2025 ;; @r{First check for the specific operations}
2026 ;; @r{that we have special handling for.}
2027 (cond ((eq operation 'insert-file-contents) @dots{})
2028 ((eq operation 'write-region) @dots{})
2030 ;; @r{Handle any operation we don't know about.}
2031 (t (let ((inhibit-file-name-handlers
2032 (cons 'my-file-handler
2033 (and (eq inhibit-file-name-operation operation)
2034 inhibit-file-name-handlers)))
2035 (inhibit-file-name-operation operation))
2036 (apply operation args)))))
2039 When a handler function decides to call the ordinary Emacs primitive for
2040 the operation at hand, it needs to prevent the primitive from calling
2041 the same handler once again, thus leading to an infinite recursion. The
2042 example above shows how to do this, with the variables
2043 @code{inhibit-file-name-handlers} and
2044 @code{inhibit-file-name-operation}. Be careful to use them exactly as
2045 shown above; the details are crucial for proper behavior in the case of
2046 multiple handlers, and for operations that have two file names that may
2049 @defvar inhibit-file-name-handlers
2050 This variable holds a list of handlers whose use is presently inhibited
2051 for a certain operation.
2054 @defvar inhibit-file-name-operation
2055 The operation for which certain handlers are presently inhibited.
2058 @defun find-file-name-handler filename &optional operation
2059 This function returns the handler function for file name @var{filename}, or
2060 @code{nil} if there is none. The argument @var{operation} should be the
2061 operation to be performed on the file---the value you will pass to the
2062 handler as its first argument when you call it. The operation is needed
2063 for comparison with @code{inhibit-file-name-operation}.
2066 @defun file-local-copy filename
2067 This function copies file @var{filename} to an ordinary non-magic file,
2068 if it isn't one already.
2070 If @var{filename} specifies a ``magic'' file name, which programs
2071 outside Emacs cannot directly read or write, this copies the contents to
2072 an ordinary file and returns that file's name.
2074 If @var{filename} is an ordinary file name, not magic, then this function
2075 does nothing and returns @code{nil}.
2078 @defun unhandled-file-name-directory filename
2079 This function returns the name of a directory that is not magic.
2080 It uses the directory part of @var{filename} if that is not magic.
2081 Otherwise, it asks the handler what to do.
2083 This is useful for running a subprocess; every subprocess must have a
2084 non-magic directory to serve as its current directory, and this function
2085 is a good way to come up with one.
2090 @section Partial Files
2091 @cindex partial files
2094 * Intro to Partial Files::
2095 * Creating a Partial File::
2096 * Detached Partial Files::
2099 @node Intro to Partial Files
2100 @subsection Intro to Partial Files
2102 A @dfn{partial file} is a section of a buffer (called the @dfn{master
2103 buffer}) that is placed in its own buffer and treated as its own file.
2104 Changes made to the partial file are not reflected in the master buffer
2105 until the partial file is ``saved'' using the standard buffer save
2106 commands. Partial files can be ``reverted'' (from the master buffer)
2107 just like normal files. When a file part is active on a master buffer,
2108 that section of the master buffer is marked as read-only. Two file
2109 parts on the same master buffer are not allowed to overlap. Partial
2110 file buffers are indicated by the words @samp{File Part} in the
2113 The master buffer knows about all the partial files that are active on
2114 it, and thus killing or reverting the master buffer will be handled
2115 properly. When the master buffer is saved, if there are any unsaved
2116 partial files active on it then the user will be given the opportunity
2117 to first save these files.
2119 When a partial file buffer is first modified, the master buffer is
2120 automatically marked as modified so that saving the master buffer will
2124 @node Creating a Partial File
2125 @subsection Creating a Partial File
2127 @deffn Command make-file-part &optional start end name buffer
2128 Make a file part on buffer @var{buffer} out of the region. Call it
2129 @var{name}. This command creates a new buffer containing the contents
2130 of the region and marks the buffer as referring to the specified buffer,
2131 called the @dfn{master buffer}. When the file-part buffer is saved, its
2132 changes are integrated back into the master buffer. When the master
2133 buffer is deleted, all file parts are deleted with it.
2135 When called from a function, expects four arguments, @var{start},
2136 @var{end}, @var{name}, and @var{buffer}, all of which are optional and
2137 default to the beginning of @var{buffer}, the end of @var{buffer}, a
2138 name generated from @var{buffer}'s name, and the current buffer,
2143 @node Detached Partial Files
2144 @subsection Detached Partial Files
2146 Every partial file has an extent in the master buffer associated with it
2147 (called the @dfn{master extent}), marking where in the master buffer the
2148 partial file begins and ends. If the text in master buffer that is
2149 contained by the extent is deleted, then the extent becomes
2150 ``detached'', meaning that it no longer refers to a specific region of
2151 the master buffer. This can happen either when the text is deleted
2152 directly or when the master buffer is reverted. Neither of these should
2153 happen in normal usage because the master buffer should generally not be
2156 Before doing any operation that references a partial file's master
2157 extent, SXEmacs checks to make sure that the extent is not detached. If
2158 this is the case, SXEmacs warns the user of this and the master extent is
2159 deleted out of the master buffer, disconnecting the file part. The file
2160 part's filename is cleared and thus must be explicitly specified if the
2161 detached file part is to be saved.
2164 @node Format Conversion
2165 @section File Format Conversion
2167 @cindex file format conversion
2168 @cindex encoding file formats
2169 @cindex decoding file formats
2170 The variable @code{format-alist} defines a list of @dfn{file formats},
2171 which describe textual representations used in files for the data (text,
2172 text-properties, and possibly other information) in a SXEmacs buffer.
2173 SXEmacs performs format conversion if appropriate when reading and writing
2176 @defvar format-alist
2177 This list contains one format definition for each defined file format.
2180 @cindex format definition
2181 Each format definition is a list of this form:
2184 (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
2187 Here is what the elements in a format definition mean:
2191 The name of this format.
2194 A documentation string for the format.
2197 A regular expression which is used to recognize files represented in
2201 A function to call to decode data in this format (to convert file data into
2202 the usual Emacs data representation).
2204 The @var{from-fn} is called with two args, @var{begin} and @var{end},
2205 which specify the part of the buffer it should convert. It should convert
2206 the text by editing it in place. Since this can change the length of the
2207 text, @var{from-fn} should return the modified end position.
2209 One responsibility of @var{from-fn} is to make sure that the beginning
2210 of the file no longer matches @var{regexp}. Otherwise it is likely to
2214 A function to call to encode data in this format (to convert
2215 the usual Emacs data representation into this format).
2217 The @var{to-fn} is called with two args, @var{begin} and @var{end},
2218 which specify the part of the buffer it should convert. There are
2219 two ways it can do the conversion:
2223 By editing the buffer in place. In this case, @var{to-fn} should
2224 return the end-position of the range of text, as modified.
2227 By returning a list of annotations. This is a list of elements of the
2228 form @code{(@var{position} . @var{string})}, where @var{position} is an
2229 integer specifying the relative position in the text to be written, and
2230 @var{string} is the annotation to add there. The list must be sorted in
2231 order of position when @var{to-fn} returns it.
2233 When @code{write-region} actually writes the text from the buffer to the
2234 file, it intermixes the specified annotations at the corresponding
2235 positions. All this takes place without modifying the buffer.
2239 A flag, @code{t} if the encoding function modifies the buffer, and
2240 @code{nil} if it works by returning a list of annotations.
2243 A mode function to call after visiting a file converted from this
2247 The function @code{insert-file-contents} automatically recognizes file
2248 formats when it reads the specified file. It checks the text of the
2249 beginning of the file against the regular expressions of the format
2250 definitions, and if it finds a match, it calls the decoding function for
2251 that format. Then it checks all the known formats over again.
2252 It keeps checking them until none of them is applicable.
2254 Visiting a file, with @code{find-file-noselect} or the commands that use
2255 it, performs conversion likewise (because it calls
2256 @code{insert-file-contents}); it also calls the mode function for each
2257 format that it decodes. It stores a list of the format names in the
2258 buffer-local variable @code{buffer-file-format}.
2260 @defvar buffer-file-format
2261 This variable states the format of the visited file. More precisely,
2262 this is a list of the file format names that were decoded in the course
2263 of visiting the current buffer's file. It is always local in all
2267 When @code{write-region} writes data into a file, it first calls the
2268 encoding functions for the formats listed in @code{buffer-file-format},
2269 in the order of appearance in the list.
2271 @deffn Command format-write-file file format
2272 This command writes the current buffer contents into the file @var{file}
2273 in format @var{format}, and makes that format the default for future
2274 saves of the buffer. The argument @var{format} is a list of format
2278 @deffn Command format-find-file file format
2279 This command finds the file @var{file}, converting it according to
2280 format @var{format}. It also makes @var{format} the default if the
2281 buffer is saved later.
2283 The argument @var{format} is a list of format names. If @var{format} is
2284 @code{nil}, no conversion takes place. Interactively, typing just
2285 @key{RET} for @var{format} specifies @code{nil}.
2288 @deffn Command format-insert-file file format &optional start end
2289 This command inserts the contents of file @var{file}, converting it
2290 according to format @var{format}. If @var{start} and @var{end} are
2291 non-@code{nil}, they specify which part of the file to read, as in
2292 @code{insert-file-contents} (@pxref{Reading from Files}).
2294 The return value is like what @code{insert-file-contents} returns: a
2295 list of the absolute file name and the length of the data inserted
2298 The argument @var{format} is a list of format names. If @var{format} is
2299 @code{nil}, no conversion takes place. Interactively, typing just
2300 @key{RET} for @var{format} specifies @code{nil}.
2303 @defvar auto-save-file-format
2304 This variable specifies the format to use for auto-saving. Its value is
2305 a list of format names, just like the value of
2306 @code{buffer-file-format}; but it is used instead of
2307 @code{buffer-file-format} for writing auto-save files. This variable
2308 is always local in all buffers.