annotate doc/lispref/files.texi @ 103157:770f32ad0bfd

(add_user_signal): Remove extern.
author YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp>
date Wed, 06 May 2009 02:26:52 +0000
parents 9e5e877e0fd8
children b269cabac20c
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
100974
cb5d2387102c Add 2009 to copyright years.
Glenn Morris <rgm@gnu.org>
parents: 100115
diff changeset
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
84116
0ba80d073e27 (setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents: 84067
diff changeset
6 @setfilename ../../info/files
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7 @node Files, Backups and Auto-Saving, Documentation, Top
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9 @chapter Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11 In Emacs, you can find, create, view, save, and otherwise work with
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12 files and file directories. This chapter describes most of the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13 file-related functions of Emacs Lisp, but a few others are described in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14 @ref{Buffers}, and those related to backups and auto-saving are
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15 described in @ref{Backups and Auto-Saving}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17 Many of the file functions take one or more arguments that are file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18 names. A file name is actually a string. Most of these functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19 expand file name arguments by calling @code{expand-file-name}, so that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20 @file{~} is handled correctly, as are relative file names (including
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21 @samp{../}). These functions don't recognize environment variable
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22 substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
23
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
24 When file I/O functions signal Lisp errors, they usually use the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
25 condition @code{file-error} (@pxref{Handling Errors}). The error
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
26 message is in most cases obtained from the operating system, according
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
27 to locale @code{system-message-locale}, and decoded using coding system
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
28 @code{locale-coding-system} (@pxref{Locales}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
29
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
30 @menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
31 * Visiting Files:: Reading files into Emacs buffers for editing.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
32 * Saving Buffers:: Writing changed buffers back into files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
33 * Reading from Files:: Reading files into buffers without visiting.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
34 * Writing to Files:: Writing new files from parts of buffers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
35 * File Locks:: Locking and unlocking files, to prevent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
36 simultaneous editing by two people.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
37 * Information about Files:: Testing existence, accessibility, size of files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
38 * Changing Files:: Renaming files, changing protection, etc.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
39 * File Names:: Decomposing and expanding file names.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
40 * Contents of Directories:: Getting a list of the files in a directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
41 * Create/Delete Dirs:: Creating and Deleting Directories.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
42 * Magic File Names:: Defining "magic" special handling
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
43 for certain file names.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
44 * Format Conversion:: Conversion to and from various file formats.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
45 @end menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
46
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
47 @node Visiting Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
48 @section Visiting Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
49 @cindex finding files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
50 @cindex visiting files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
51
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
52 Visiting a file means reading a file into a buffer. Once this is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
53 done, we say that the buffer is @dfn{visiting} that file, and call the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
54 file ``the visited file'' of the buffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
55
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
56 A file and a buffer are two different things. A file is information
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
57 recorded permanently in the computer (unless you delete it). A buffer,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
58 on the other hand, is information inside of Emacs that will vanish at
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
59 the end of the editing session (or when you kill the buffer). Usually,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
60 a buffer contains information that you have copied from a file; then we
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
61 say the buffer is visiting that file. The copy in the buffer is what
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
62 you modify with editing commands. Such changes to the buffer do not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
63 change the file; therefore, to make the changes permanent, you must
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
64 @dfn{save} the buffer, which means copying the altered buffer contents
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
65 back into the file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
66
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
67 In spite of the distinction between files and buffers, people often
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
68 refer to a file when they mean a buffer and vice-versa. Indeed, we say,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
69 ``I am editing a file,'' rather than, ``I am editing a buffer that I
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
70 will soon save as a file of the same name.'' Humans do not usually need
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
71 to make the distinction explicit. When dealing with a computer program,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
72 however, it is good to keep the distinction in mind.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
73
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
74 @menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
75 * Visiting Functions:: The usual interface functions for visiting.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
76 * Subroutines of Visiting:: Lower-level subroutines that they use.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
77 @end menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
78
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
79 @node Visiting Functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
80 @subsection Functions for Visiting Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
81
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
82 This section describes the functions normally used to visit files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
83 For historical reasons, these functions have names starting with
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
84 @samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
85 functions and variables that access the visited file name of a buffer or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
86 that find an existing buffer by its visited file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
87
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
88 In a Lisp program, if you want to look at the contents of a file but
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
89 not alter it, the fastest way is to use @code{insert-file-contents} in a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
90 temporary buffer. Visiting the file is not necessary and takes longer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
91 @xref{Reading from Files}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
92
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
93 @deffn Command find-file filename &optional wildcards
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
94 This command selects a buffer visiting the file @var{filename},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
95 using an existing buffer if there is one, and otherwise creating a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
96 new buffer and reading the file into it. It also returns that buffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
97
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
98 Aside from some technical details, the body of the @code{find-file}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
99 function is basically equivalent to:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
100
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
101 @smallexample
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
102 (switch-to-buffer (find-file-noselect filename nil nil wildcards))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
103 @end smallexample
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
104
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
105 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
106 (See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
107
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
108 If @var{wildcards} is non-@code{nil}, which is always true in an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
109 interactive call, then @code{find-file} expands wildcard characters in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
110 @var{filename} and visits all the matching files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
111
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
112 When @code{find-file} is called interactively, it prompts for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
113 @var{filename} in the minibuffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
114 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
115
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
116 @defun find-file-noselect filename &optional nowarn rawfile wildcards
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
117 This function is the guts of all the file-visiting functions. It
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
118 returns a buffer visiting the file @var{filename}. You may make the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
119 buffer current or display it in a window if you wish, but this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
120 function does not do so.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
121
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
122 The function returns an existing buffer if there is one; otherwise it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
123 creates a new buffer and reads the file into it. When
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
124 @code{find-file-noselect} uses an existing buffer, it first verifies
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
125 that the file has not changed since it was last visited or saved in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
126 that buffer. If the file has changed, this function asks the user
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
127 whether to reread the changed file. If the user says @samp{yes}, any
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
128 edits previously made in the buffer are lost.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
129
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
130 Reading the file involves decoding the file's contents (@pxref{Coding
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
131 Systems}), including end-of-line conversion, and format conversion
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
132 (@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
133 then @code{find-file-noselect} expands wildcard characters in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
134 @var{filename} and visits all the matching files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
135
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
136 This function displays warning or advisory messages in various peculiar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
137 cases, unless the optional argument @var{nowarn} is non-@code{nil}. For
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
138 example, if it needs to create a buffer, and there is no file named
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
139 @var{filename}, it displays the message @samp{(New file)} in the echo
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
140 area, and leaves the buffer empty.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
141
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
142 The @code{find-file-noselect} function normally calls
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
143 @code{after-find-file} after reading the file (@pxref{Subroutines of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
144 Visiting}). That function sets the buffer major mode, parses local
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
145 variables, warns the user if there exists an auto-save file more recent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
146 than the file just visited, and finishes by running the functions in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
147 @code{find-file-hook}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
148
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
149 If the optional argument @var{rawfile} is non-@code{nil}, then
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
150 @code{after-find-file} is not called, and the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
151 @code{find-file-not-found-functions} are not run in case of failure.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
152 What's more, a non-@code{nil} @var{rawfile} value suppresses coding
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
153 system conversion and format conversion.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
154
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
155 The @code{find-file-noselect} function usually returns the buffer that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
156 is visiting the file @var{filename}. But, if wildcards are actually
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
157 used and expanded, it returns a list of buffers that are visiting the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
158 various files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
159
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
160 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
161 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
162 (find-file-noselect "/etc/fstab")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
163 @result{} #<buffer fstab>
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
164 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
165 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
166 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
167
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
168 @deffn Command find-file-other-window filename &optional wildcards
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
169 This command selects a buffer visiting the file @var{filename}, but
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
170 does so in a window other than the selected window. It may use another
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
171 existing window or split a window; see @ref{Displaying Buffers}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
172
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
173 When this command is called interactively, it prompts for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
174 @var{filename}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
175 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
176
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
177 @deffn Command find-file-read-only filename &optional wildcards
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
178 This command selects a buffer visiting the file @var{filename}, like
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
179 @code{find-file}, but it marks the buffer as read-only. @xref{Read Only
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
180 Buffers}, for related functions and variables.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
181
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
182 When this command is called interactively, it prompts for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
183 @var{filename}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
184 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
185
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
186 @deffn Command view-file filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
187 This command visits @var{filename} using View mode, returning to the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
188 previous buffer when you exit View mode. View mode is a minor mode that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
189 provides commands to skim rapidly through the file, but does not let you
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
190 modify the text. Entering View mode runs the normal hook
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
191 @code{view-mode-hook}. @xref{Hooks}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
192
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
193 When @code{view-file} is called interactively, it prompts for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
194 @var{filename}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
195 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
196
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
197 @defopt find-file-wildcards
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
198 If this variable is non-@code{nil}, then the various @code{find-file}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
199 commands check for wildcard characters and visit all the files that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
200 match them (when invoked interactively or when their @var{wildcards}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
201 argument is non-@code{nil}). If this option is @code{nil}, then
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
202 the @code{find-file} commands ignore their @var{wildcards} argument
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
203 and never treat wildcard characters specially.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
204 @end defopt
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
205
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
206 @defvar find-file-hook
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
207 The value of this variable is a list of functions to be called after a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
208 file is visited. The file's local-variables specification (if any) will
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
209 have been processed before the hooks are run. The buffer visiting the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
210 file is current when the hook functions are run.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
211
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
212 This variable is a normal hook. @xref{Hooks}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
213 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
214
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
215 @defvar find-file-not-found-functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
216 The value of this variable is a list of functions to be called when
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
217 @code{find-file} or @code{find-file-noselect} is passed a nonexistent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
218 file name. @code{find-file-noselect} calls these functions as soon as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
219 it detects a nonexistent file. It calls them in the order of the list,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
220 until one of them returns non-@code{nil}. @code{buffer-file-name} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
221 already set up.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
222
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
223 This is not a normal hook because the values of the functions are
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
224 used, and in many cases only some of the functions are called.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
225 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
226
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
227 @node Subroutines of Visiting
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
228 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
229 @subsection Subroutines of Visiting
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
230
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
231 The @code{find-file-noselect} function uses two important subroutines
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
232 which are sometimes useful in user Lisp code: @code{create-file-buffer}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
233 and @code{after-find-file}. This section explains how to use them.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
234
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
235 @defun create-file-buffer filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
236 This function creates a suitably named buffer for visiting
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
237 @var{filename}, and returns it. It uses @var{filename} (sans directory)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
238 as the name if that name is free; otherwise, it appends a string such as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
239 @samp{<2>} to get an unused name. See also @ref{Creating Buffers}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
240
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
241 @strong{Please note:} @code{create-file-buffer} does @emph{not}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
242 associate the new buffer with a file and does not select the buffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
243 It also does not use the default major mode.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
244
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
245 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
246 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
247 (create-file-buffer "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
248 @result{} #<buffer foo>
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
249 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
250 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
251 (create-file-buffer "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
252 @result{} #<buffer foo<2>>
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
253 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
254 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
255 (create-file-buffer "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
256 @result{} #<buffer foo<3>>
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
257 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
258 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
259
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
260 This function is used by @code{find-file-noselect}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
261 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
262 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
263
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
264 @defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
265 This function sets the buffer major mode, and parses local variables
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
266 (@pxref{Auto Major Mode}). It is called by @code{find-file-noselect}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
267 and by the default revert function (@pxref{Reverting}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
268
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
269 @cindex new file message
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
270 @cindex file open error
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
271 If reading the file got an error because the file does not exist, but
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
272 its directory does exist, the caller should pass a non-@code{nil} value
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
273 for @var{error}. In that case, @code{after-find-file} issues a warning:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
274 @samp{(New file)}. For more serious errors, the caller should usually not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
275 call @code{after-find-file}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
276
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
277 If @var{warn} is non-@code{nil}, then this function issues a warning
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
278 if an auto-save file exists and is more recent than the visited file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
279
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
280 If @var{noauto} is non-@code{nil}, that says not to enable or disable
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
281 Auto-Save mode. The mode remains enabled if it was enabled before.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
282
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
283 If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
284 means this call was from @code{revert-buffer}. This has no direct
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
285 effect, but some mode functions and hook functions check the value
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
286 of this variable.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
287
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
288 If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
289 major mode, don't process local variables specifications in the file,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
290 and don't run @code{find-file-hook}. This feature is used by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
291 @code{revert-buffer} in some cases.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
292
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
293 The last thing @code{after-find-file} does is call all the functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
294 in the list @code{find-file-hook}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
295 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
296
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
297 @node Saving Buffers
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
298 @section Saving Buffers
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
299 @cindex saving buffers
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
300
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
301 When you edit a file in Emacs, you are actually working on a buffer
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
302 that is visiting that file---that is, the contents of the file are
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
303 copied into the buffer and the copy is what you edit. Changes to the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
304 buffer do not change the file until you @dfn{save} the buffer, which
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
305 means copying the contents of the buffer into the file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
306
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
307 @deffn Command save-buffer &optional backup-option
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
308 This function saves the contents of the current buffer in its visited
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
309 file if the buffer has been modified since it was last visited or saved.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
310 Otherwise it does nothing.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
311
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
312 @code{save-buffer} is responsible for making backup files. Normally,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
313 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
314 file only if this is the first save since visiting the file. Other
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
315 values for @var{backup-option} request the making of backup files in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
316 other circumstances:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
317
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
318 @itemize @bullet
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
319 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
320 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
321 @code{save-buffer} function marks this version of the file to be
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
322 backed up when the buffer is next saved.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
323
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
324 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
325 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
326 @code{save-buffer} function unconditionally backs up the previous
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
327 version of the file before saving it.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
328
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
329 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
330 With an argument of 0, unconditionally do @emph{not} make any backup file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
331 @end itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
332 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
333
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
334 @deffn Command save-some-buffers &optional save-silently-p pred
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
335 @anchor{Definition of save-some-buffers}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
336 This command saves some modified file-visiting buffers. Normally it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
337 asks the user about each buffer. But if @var{save-silently-p} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
338 non-@code{nil}, it saves all the file-visiting buffers without querying
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
339 the user.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
340
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
341 The optional @var{pred} argument controls which buffers to ask about
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
342 (or to save silently if @var{save-silently-p} is non-@code{nil}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
343 If it is @code{nil}, that means to ask only about file-visiting buffers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
344 If it is @code{t}, that means also offer to save certain other non-file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
345 buffers---those that have a non-@code{nil} buffer-local value of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
346 @code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
347 @samp{yes} to saving a non-file buffer is asked to specify the file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
348 name to use. The @code{save-buffers-kill-emacs} function passes the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
349 value @code{t} for @var{pred}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
350
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
351 If @var{pred} is neither @code{t} nor @code{nil}, then it should be
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
352 a function of no arguments. It will be called in each buffer to decide
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
353 whether to offer to save that buffer. If it returns a non-@code{nil}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
354 value in a certain buffer, that means do offer to save that buffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
355 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
356
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
357 @deffn Command write-file filename &optional confirm
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
358 @anchor{Definition of write-file}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
359 This function writes the current buffer into file @var{filename}, makes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
360 the buffer visit that file, and marks it not modified. Then it renames
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
361 the buffer based on @var{filename}, appending a string like @samp{<2>}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
362 if necessary to make a unique buffer name. It does most of this work by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
363 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
364 @code{save-buffer}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
365
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
366 If @var{confirm} is non-@code{nil}, that means to ask for confirmation
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
367 before overwriting an existing file. Interactively, confirmation is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
368 required, unless the user supplies a prefix argument.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
369
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
370 If @var{filename} is an existing directory, or a symbolic link to one,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
371 @code{write-file} uses the name of the visited file, in directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
372 @var{filename}. If the buffer is not visiting a file, it uses the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
373 buffer name instead.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
374 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
375
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
376 Saving a buffer runs several hooks. It also performs format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
377 conversion (@pxref{Format Conversion}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
378
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
379 @defvar write-file-functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
380 The value of this variable is a list of functions to be called before
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
381 writing out a buffer to its visited file. If one of them returns
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
382 non-@code{nil}, the file is considered already written and the rest of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
383 the functions are not called, nor is the usual code for writing the file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
384 executed.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
385
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
386 If a function in @code{write-file-functions} returns non-@code{nil}, it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
387 is responsible for making a backup file (if that is appropriate).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
388 To do so, execute the following code:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
389
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
390 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
391 (or buffer-backed-up (backup-buffer))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
392 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
393
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
394 You might wish to save the file modes value returned by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
395 @code{backup-buffer} and use that (if non-@code{nil}) to set the mode
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
396 bits of the file that you write. This is what @code{save-buffer}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
397 normally does. @xref{Making Backups,, Making Backup Files}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
398
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
399 The hook functions in @code{write-file-functions} are also responsible
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
400 for encoding the data (if desired): they must choose a suitable coding
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
401 system and end-of-line conversion (@pxref{Lisp and Coding Systems}),
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
402 perform the encoding (@pxref{Explicit Encoding}), and set
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
403 @code{last-coding-system-used} to the coding system that was used
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
404 (@pxref{Encoding and I/O}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
405
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
406 If you set this hook locally in a buffer, it is assumed to be
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
407 associated with the file or the way the contents of the buffer were
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
408 obtained. Thus the variable is marked as a permanent local, so that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
409 changing the major mode does not alter a buffer-local value. On the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
410 other hand, calling @code{set-visited-file-name} will reset it.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
411 If this is not what you want, you might like to use
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
412 @code{write-contents-functions} instead.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
413
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
414 Even though this is not a normal hook, you can use @code{add-hook} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
415 @code{remove-hook} to manipulate the list. @xref{Hooks}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
416 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
417
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
418 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
419 @defvar write-contents-functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
420 This works just like @code{write-file-functions}, but it is intended
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
421 for hooks that pertain to the buffer's contents, not to the particular
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
422 visited file or its location. Such hooks are usually set up by major
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
423 modes, as buffer-local bindings for this variable. This variable
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
424 automatically becomes buffer-local whenever it is set; switching to a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
425 new major mode always resets this variable, but calling
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
426 @code{set-visited-file-name} does not.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
427
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
428 If any of the functions in this hook returns non-@code{nil}, the file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
429 is considered already written and the rest are not called and neither
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
430 are the functions in @code{write-file-functions}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
431 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
432
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
433 @defopt before-save-hook
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
434 This normal hook runs before a buffer is saved in its visited file,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
435 regardless of whether that is done normally or by one of the hooks
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
436 described above. For instance, the @file{copyright.el} program uses
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
437 this hook to make sure the file you are saving has the current year in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
438 its copyright notice.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
439 @end defopt
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
440
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
441 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
442 @defopt after-save-hook
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
443 This normal hook runs after a buffer has been saved in its visited file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
444 One use of this hook is in Fast Lock mode; it uses this hook to save the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
445 highlighting information in a cache file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
446 @end defopt
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
447
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
448 @defopt file-precious-flag
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
449 If this variable is non-@code{nil}, then @code{save-buffer} protects
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
450 against I/O errors while saving by writing the new file to a temporary
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
451 name instead of the name it is supposed to have, and then renaming it to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
452 the intended name after it is clear there are no errors. This procedure
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
453 prevents problems such as a lack of disk space from resulting in an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
454 invalid file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
455
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
456 As a side effect, backups are necessarily made by copying. @xref{Rename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
457 or Copy}. Yet, at the same time, saving a precious file always breaks
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
458 all hard links between the file you save and other file names.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
459
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
460 Some modes give this variable a non-@code{nil} buffer-local value
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
461 in particular buffers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
462 @end defopt
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
463
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
464 @defopt require-final-newline
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
465 This variable determines whether files may be written out that do
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
466 @emph{not} end with a newline. If the value of the variable is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
467 @code{t}, then @code{save-buffer} silently adds a newline at the end of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
468 the file whenever the buffer being saved does not already end in one.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
469 If the value of the variable is non-@code{nil}, but not @code{t}, then
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
470 @code{save-buffer} asks the user whether to add a newline each time the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
471 case arises.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
472
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
473 If the value of the variable is @code{nil}, then @code{save-buffer}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
474 doesn't add newlines at all. @code{nil} is the default value, but a few
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
475 major modes set it to @code{t} in particular buffers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
476 @end defopt
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
477
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
478 See also the function @code{set-visited-file-name} (@pxref{Buffer File
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
479 Name}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
480
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
481 @node Reading from Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
482 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
483 @section Reading from Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
484 @cindex reading from files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
485
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
486 You can copy a file from the disk and insert it into a buffer
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
487 using the @code{insert-file-contents} function. Don't use the user-level
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
488 command @code{insert-file} in a Lisp program, as that sets the mark.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
489
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
490 @defun insert-file-contents filename &optional visit beg end replace
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
491 This function inserts the contents of file @var{filename} into the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
492 current buffer after point. It returns a list of the absolute file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
493 and the length of the data inserted. An error is signaled if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
494 @var{filename} is not the name of a file that can be read.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
495
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
496 The function @code{insert-file-contents} checks the file contents
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
497 against the defined file formats, and converts the file contents if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
498 appropriate and also calls the functions in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
499 the list @code{after-insert-file-functions}. @xref{Format Conversion}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
500 Normally, one of the functions in the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
501 @code{after-insert-file-functions} list determines the coding system
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
502 (@pxref{Coding Systems}) used for decoding the file's contents,
101050
ceb69a8a308a (Reading from Files): Document that null bytes force no-conversion when visiting
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
503 including end-of-line conversion. However, if the file contains null
ceb69a8a308a (Reading from Files): Document that null bytes force no-conversion when visiting
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
504 bytes, it is by default visited without any code conversions; see
ceb69a8a308a (Reading from Files): Document that null bytes force no-conversion when visiting
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
505 @ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to
ceb69a8a308a (Reading from Files): Document that null bytes force no-conversion when visiting
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
506 control this behavior.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
507
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
508 If @var{visit} is non-@code{nil}, this function additionally marks the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
509 buffer as unmodified and sets up various fields in the buffer so that it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
510 is visiting the file @var{filename}: these include the buffer's visited
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
511 file name and its last save file modtime. This feature is used by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
512 @code{find-file-noselect} and you probably should not use it yourself.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
513
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
514 If @var{beg} and @var{end} are non-@code{nil}, they should be integers
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
515 specifying the portion of the file to insert. In this case, @var{visit}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
516 must be @code{nil}. For example,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
517
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
518 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
519 (insert-file-contents filename nil 0 500)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
520 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
521
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
522 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
523 inserts the first 500 characters of a file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
524
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
525 If the argument @var{replace} is non-@code{nil}, it means to replace the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
526 contents of the buffer (actually, just the accessible portion) with the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
527 contents of the file. This is better than simply deleting the buffer
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
528 contents and inserting the whole file, because (1) it preserves some
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
529 marker positions and (2) it puts less data in the undo list.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
530
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
531 It is possible to read a special file (such as a FIFO or an I/O device)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
532 with @code{insert-file-contents}, as long as @var{replace} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
533 @var{visit} are @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
534 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
535
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
536 @defun insert-file-contents-literally filename &optional visit beg end replace
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
537 This function works like @code{insert-file-contents} except that it does
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
538 not do format decoding (@pxref{Format Conversion}), does not do
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
539 character code conversion (@pxref{Coding Systems}), does not run
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
540 @code{find-file-hook}, does not perform automatic uncompression, and so
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
541 on.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
542 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
543
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
544 If you want to pass a file name to another process so that another
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
545 program can read the file, use the function @code{file-local-copy}; see
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
546 @ref{Magic File Names}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
547
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
548 @node Writing to Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
549 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
550 @section Writing to Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
551 @cindex writing to files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
552
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
553 You can write the contents of a buffer, or part of a buffer, directly
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
554 to a file on disk using the @code{append-to-file} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
555 @code{write-region} functions. Don't use these functions to write to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
556 files that are being visited; that could cause confusion in the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
557 mechanisms for visiting.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
558
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
559 @deffn Command append-to-file start end filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
560 This function appends the contents of the region delimited by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
561 @var{start} and @var{end} in the current buffer to the end of file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
562 @var{filename}. If that file does not exist, it is created. This
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
563 function returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
564
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
565 An error is signaled if @var{filename} specifies a nonwritable file,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
566 or a nonexistent file in a directory where files cannot be created.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
567
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
568 When called from Lisp, this function is completely equivalent to:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
569
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
570 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
571 (write-region start end filename t)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
572 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
573 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
574
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
575 @deffn Command write-region start end filename &optional append visit lockname mustbenew
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
576 This function writes the region delimited by @var{start} and @var{end}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
577 in the current buffer into the file specified by @var{filename}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
578
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
579 If @var{start} is @code{nil}, then the command writes the entire buffer
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
580 contents (@emph{not} just the accessible portion) to the file and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
581 ignores @var{end}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
582
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
583 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
584 If @var{start} is a string, then @code{write-region} writes or appends
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
585 that string, rather than text from the buffer. @var{end} is ignored in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
586 this case.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
587
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
588 If @var{append} is non-@code{nil}, then the specified text is appended
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
589 to the existing file contents (if any). If @var{append} is an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
590 integer, @code{write-region} seeks to that byte offset from the start
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
591 of the file and writes the data from there.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
592
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
593 If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
594 for confirmation if @var{filename} names an existing file. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
595 @var{mustbenew} is the symbol @code{excl}, then @code{write-region}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
596 does not ask for confirmation, but instead it signals an error
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
597 @code{file-already-exists} if the file already exists.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
598
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
599 The test for an existing file, when @var{mustbenew} is @code{excl}, uses
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
600 a special system feature. At least for files on a local disk, there is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
601 no chance that some other program could create a file of the same name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
602 before Emacs does, without Emacs's noticing.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
603
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
604 If @var{visit} is @code{t}, then Emacs establishes an association
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
605 between the buffer and the file: the buffer is then visiting that file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
606 It also sets the last file modification time for the current buffer to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
607 @var{filename}'s modtime, and marks the buffer as not modified. This
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
608 feature is used by @code{save-buffer}, but you probably should not use
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
609 it yourself.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
610
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
611 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
612 If @var{visit} is a string, it specifies the file name to visit. This
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
613 way, you can write the data to one file (@var{filename}) while recording
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
614 the buffer as visiting another file (@var{visit}). The argument
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
615 @var{visit} is used in the echo area message and also for file locking;
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
616 @var{visit} is stored in @code{buffer-file-name}. This feature is used
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
617 to implement @code{file-precious-flag}; don't use it yourself unless you
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
618 really know what you're doing.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
619
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
620 The optional argument @var{lockname}, if non-@code{nil}, specifies the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
621 file name to use for purposes of locking and unlocking, overriding
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
622 @var{filename} and @var{visit} for that purpose.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
623
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
624 The function @code{write-region} converts the data which it writes to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
625 the appropriate file formats specified by @code{buffer-file-format}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
626 and also calls the functions in the list
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
627 @code{write-region-annotate-functions}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
628 @xref{Format Conversion}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
629
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
630 Normally, @code{write-region} displays the message @samp{Wrote
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
631 @var{filename}} in the echo area. If @var{visit} is neither @code{t}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
632 nor @code{nil} nor a string, then this message is inhibited. This
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
633 feature is useful for programs that use files for internal purposes,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
634 files that the user does not need to know about.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
635 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
636
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
637 @defmac with-temp-file file body@dots{}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
638 @anchor{Definition of with-temp-file}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
639 The @code{with-temp-file} macro evaluates the @var{body} forms with a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
640 temporary buffer as the current buffer; then, at the end, it writes the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
641 buffer contents into file @var{file}. It kills the temporary buffer
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
642 when finished, restoring the buffer that was current before the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
643 @code{with-temp-file} form. Then it returns the value of the last form
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
644 in @var{body}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
645
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
646 The current buffer is restored even in case of an abnormal exit via
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
647 @code{throw} or error (@pxref{Nonlocal Exits}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
648
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
649 See also @code{with-temp-buffer} in @ref{Definition of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
650 with-temp-buffer,, The Current Buffer}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
651 @end defmac
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
652
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
653 @node File Locks
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
654 @section File Locks
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
655 @cindex file locks
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
656 @cindex lock file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
657
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
658 When two users edit the same file at the same time, they are likely
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
659 to interfere with each other. Emacs tries to prevent this situation
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
660 from arising by recording a @dfn{file lock} when a file is being
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
661 modified. (File locks are not implemented on Microsoft systems.)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
662 Emacs can then detect the first attempt to modify a buffer visiting a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
663 file that is locked by another Emacs job, and ask the user what to do.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
664 The file lock is really a file, a symbolic link with a special name,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
665 stored in the same directory as the file you are editing.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
666
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
667 When you access files using NFS, there may be a small probability that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
668 you and another user will both lock the same file ``simultaneously.''
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
669 If this happens, it is possible for the two users to make changes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
670 simultaneously, but Emacs will still warn the user who saves second.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
671 Also, the detection of modification of a buffer visiting a file changed
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
672 on disk catches some cases of simultaneous editing; see
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
673 @ref{Modification Time}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
674
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
675 @defun file-locked-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
676 This function returns @code{nil} if the file @var{filename} is not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
677 locked. It returns @code{t} if it is locked by this Emacs process, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
678 it returns the name of the user who has locked it if it is locked by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
679 some other job.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
680
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
681 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
682 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
683 (file-locked-p "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
684 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
685 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
686 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
687 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
688
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
689 @defun lock-buffer &optional filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
690 This function locks the file @var{filename}, if the current buffer is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
691 modified. The argument @var{filename} defaults to the current buffer's
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
692 visited file. Nothing is done if the current buffer is not visiting a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
693 file, or is not modified, or if the system does not support locking.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
694 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
695
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
696 @defun unlock-buffer
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
697 This function unlocks the file being visited in the current buffer,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
698 if the buffer is modified. If the buffer is not modified, then
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
699 the file should not be locked, so this function does nothing. It also
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
700 does nothing if the current buffer is not visiting a file, or if the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
701 system does not support locking.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
702 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
703
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
704 File locking is not supported on some systems. On systems that do not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
705 support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
706 @code{file-locked-p} do nothing and return @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
707
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
708 @defun ask-user-about-lock file other-user
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
709 This function is called when the user tries to modify @var{file}, but it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
710 is locked by another user named @var{other-user}. The default
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
711 definition of this function asks the user to say what to do. The value
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
712 this function returns determines what Emacs does next:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
713
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
714 @itemize @bullet
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
715 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
716 A value of @code{t} says to grab the lock on the file. Then
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
717 this user may edit the file and @var{other-user} loses the lock.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
718
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
719 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
720 A value of @code{nil} says to ignore the lock and let this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
721 user edit the file anyway.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
722
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
723 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
724 @kindex file-locked
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
725 This function may instead signal a @code{file-locked} error, in which
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
726 case the change that the user was about to make does not take place.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
727
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
728 The error message for this error looks like this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
729
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
730 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
731 @error{} File is locked: @var{file} @var{other-user}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
732 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
733
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
734 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
735 where @code{file} is the name of the file and @var{other-user} is the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
736 name of the user who has locked the file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
737 @end itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
738
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
739 If you wish, you can replace the @code{ask-user-about-lock} function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
740 with your own version that makes the decision in another way. The code
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
741 for its usual definition is in @file{userlock.el}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
742 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
743
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
744 @node Information about Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
745 @section Information about Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
746 @cindex file, information about
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
747
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
748 The functions described in this section all operate on strings that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
749 designate file names. With a few exceptions, all the functions have
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
750 names that begin with the word @samp{file}. These functions all
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
751 return information about actual files or directories, so their
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
752 arguments must all exist as actual files or directories unless
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
753 otherwise noted.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
754
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
755 @menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
756 * Testing Accessibility:: Is a given file readable? Writable?
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
757 * Kinds of Files:: Is it a directory? A symbolic link?
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
758 * Truenames:: Eliminating symbolic links from a file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
759 * File Attributes:: How large is it? Any other names? Etc.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
760 * Locating Files:: How to find a file in standard places.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
761 @end menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
762
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
763 @node Testing Accessibility
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
764 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
765 @subsection Testing Accessibility
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
766 @cindex accessibility of a file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
767 @cindex file accessibility
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
768
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
769 These functions test for permission to access a file in specific
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
770 ways. Unless explicitly stated otherwise, they recursively follow
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
771 symbolic links for their file name arguments, at all levels (at the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
772 level of the file itself and at all levels of parent directories).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
773
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
774 @defun file-exists-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
775 This function returns @code{t} if a file named @var{filename} appears
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
776 to exist. This does not mean you can necessarily read the file, only
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
777 that you can find out its attributes. (On Unix and GNU/Linux, this is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
778 true if the file exists and you have execute permission on the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
779 containing directories, regardless of the protection of the file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
780 itself.)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
781
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
782 If the file does not exist, or if fascist access control policies
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
783 prevent you from finding the attributes of the file, this function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
784 returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
785
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
786 Directories are files, so @code{file-exists-p} returns @code{t} when
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
787 given a directory name. However, symbolic links are treated
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
788 specially; @code{file-exists-p} returns @code{t} for a symbolic link
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
789 name only if the target file exists.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
790 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
791
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
792 @defun file-readable-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
793 This function returns @code{t} if a file named @var{filename} exists
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
794 and you can read it. It returns @code{nil} otherwise.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
795
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
796 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
797 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
798 (file-readable-p "files.texi")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
799 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
800 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
801 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
802 (file-exists-p "/usr/spool/mqueue")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
803 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
804 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
805 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
806 (file-readable-p "/usr/spool/mqueue")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
807 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
808 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
809 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
810 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
811
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
812 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
813 @defun file-executable-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
814 This function returns @code{t} if a file named @var{filename} exists and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
815 you can execute it. It returns @code{nil} otherwise. On Unix and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
816 GNU/Linux, if the file is a directory, execute permission means you can
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
817 check the existence and attributes of files inside the directory, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
818 open those files if their modes permit.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
819 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
820
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
821 @defun file-writable-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
822 This function returns @code{t} if the file @var{filename} can be written
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
823 or created by you, and @code{nil} otherwise. A file is writable if the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
824 file exists and you can write it. It is creatable if it does not exist,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
825 but the specified directory does exist and you can write in that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
826 directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
827
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
828 In the third example below, @file{foo} is not writable because the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
829 parent directory does not exist, even though the user could create such
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
830 a directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
831
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
832 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
833 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
834 (file-writable-p "~/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
835 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
836 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
837 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
838 (file-writable-p "/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
839 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
840 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
841 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
842 (file-writable-p "~/no-such-dir/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
843 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
844 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
845 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
846 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
847
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
848 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
849 @defun file-accessible-directory-p dirname
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
850 This function returns @code{t} if you have permission to open existing
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
851 files in the directory whose name as a file is @var{dirname};
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
852 otherwise (or if there is no such directory), it returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
853 The value of @var{dirname} may be either a directory name (such as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
854 @file{/foo/}) or the file name of a file which is a directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
855 (such as @file{/foo}, without the final slash).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
856
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
857 Example: after the following,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
858
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
859 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
860 (file-accessible-directory-p "/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
861 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
862 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
863
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
864 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
865 we can deduce that any attempt to read a file in @file{/foo/} will
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
866 give an error.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
867 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
868
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
869 @defun access-file filename string
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
870 This function opens file @var{filename} for reading, then closes it and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
871 returns @code{nil}. However, if the open fails, it signals an error
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
872 using @var{string} as the error message text.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
873 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
874
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
875 @defun file-ownership-preserved-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
876 This function returns @code{t} if deleting the file @var{filename} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
877 then creating it anew would keep the file's owner unchanged. It also
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
878 returns @code{t} for nonexistent files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
879
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
880 If @var{filename} is a symbolic link, then, unlike the other functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
881 discussed here, @code{file-ownership-preserved-p} does @emph{not}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
882 replace @var{filename} with its target. However, it does recursively
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
883 follow symbolic links at all levels of parent directories.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
884 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
885
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
886 @defun file-newer-than-file-p filename1 filename2
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
887 @cindex file age
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
888 @cindex file modification time
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
889 This function returns @code{t} if the file @var{filename1} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
890 newer than file @var{filename2}. If @var{filename1} does not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
891 exist, it returns @code{nil}. If @var{filename1} does exist, but
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
892 @var{filename2} does not, it returns @code{t}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
893
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
894 In the following example, assume that the file @file{aug-19} was written
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
895 on the 19th, @file{aug-20} was written on the 20th, and the file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
896 @file{no-file} doesn't exist at all.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
897
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
898 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
899 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
900 (file-newer-than-file-p "aug-19" "aug-20")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
901 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
902 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
903 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
904 (file-newer-than-file-p "aug-20" "aug-19")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
905 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
906 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
907 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
908 (file-newer-than-file-p "aug-19" "no-file")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
909 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
910 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
911 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
912 (file-newer-than-file-p "no-file" "aug-19")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
913 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
914 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
915 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
916
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
917 You can use @code{file-attributes} to get a file's last modification
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
918 time as a list of two numbers. @xref{File Attributes}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
919 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
920
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
921 @node Kinds of Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
922 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
923 @subsection Distinguishing Kinds of Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
924
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
925 This section describes how to distinguish various kinds of files, such
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
926 as directories, symbolic links, and ordinary files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
927
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
928 @defun file-symlink-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
929 @cindex file symbolic links
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
930 If the file @var{filename} is a symbolic link, the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
931 @code{file-symlink-p} function returns the (non-recursive) link target
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
932 as a string. (Determining the file name that the link points to from
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
933 the target is nontrivial.) First, this function recursively follows
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
934 symbolic links at all levels of parent directories.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
935
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
936 If the file @var{filename} is not a symbolic link (or there is no such file),
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
937 @code{file-symlink-p} returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
938
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
939 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
940 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
941 (file-symlink-p "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
942 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
943 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
944 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
945 (file-symlink-p "sym-link")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
946 @result{} "foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
947 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
948 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
949 (file-symlink-p "sym-link2")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
950 @result{} "sym-link"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
951 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
952 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
953 (file-symlink-p "/bin")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
954 @result{} "/pub/bin"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
955 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
956 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
957
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
958 @c !!! file-symlink-p: should show output of ls -l for comparison
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
959 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
960
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
961 The next two functions recursively follow symbolic links at
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
962 all levels for @var{filename}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
963
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
964 @defun file-directory-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
965 This function returns @code{t} if @var{filename} is the name of an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
966 existing directory, @code{nil} otherwise.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
967
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
968 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
969 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
970 (file-directory-p "~rms")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
971 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
972 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
973 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
974 (file-directory-p "~rms/lewis/files.texi")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
975 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
976 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
977 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
978 (file-directory-p "~rms/lewis/no-such-file")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
979 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
980 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
981 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
982 (file-directory-p "$HOME")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
983 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
984 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
985 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
986 (file-directory-p
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
987 (substitute-in-file-name "$HOME"))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
988 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
989 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
990 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
991 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
992
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
993 @defun file-regular-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
994 This function returns @code{t} if the file @var{filename} exists and is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
995 a regular file (not a directory, named pipe, terminal, or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
996 other I/O device).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
997 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
998
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
999 @node Truenames
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1000 @subsection Truenames
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1001 @cindex truename (of file)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1002
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1003 @c Emacs 19 features
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1004 The @dfn{truename} of a file is the name that you get by following
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1005 symbolic links at all levels until none remain, then simplifying away
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1006 @samp{.}@: and @samp{..}@: appearing as name components. This results
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1007 in a sort of canonical name for the file. A file does not always have a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1008 unique truename; the number of distinct truenames a file has is equal to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1009 the number of hard links to the file. However, truenames are useful
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1010 because they eliminate symbolic links as a cause of name variation.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1011
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1012 @defun file-truename filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1013 The function @code{file-truename} returns the truename of the file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1014 @var{filename}. The argument must be an absolute file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1015
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1016 This function does not expand environment variables. Only
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1017 @code{substitute-in-file-name} does that. @xref{Definition of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1018 substitute-in-file-name}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1019
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1020 If you may need to follow symbolic links preceding @samp{..}@:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1021 appearing as a name component, you should make sure to call
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1022 @code{file-truename} without prior direct or indirect calls to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1023 @code{expand-file-name}, as otherwise the file name component
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1024 immediately preceding @samp{..} will be ``simplified away'' before
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1025 @code{file-truename} is called. To eliminate the need for a call to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1026 @code{expand-file-name}, @code{file-truename} handles @samp{~} in the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1027 same way that @code{expand-file-name} does. @xref{File Name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1028 Expansion,, Functions that Expand Filenames}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1029 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1030
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1031 @defun file-chase-links filename &optional limit
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1032 This function follows symbolic links, starting with @var{filename},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1033 until it finds a file name which is not the name of a symbolic link.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1034 Then it returns that file name. This function does @emph{not} follow
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1035 symbolic links at the level of parent directories.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1036
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1037 If you specify a number for @var{limit}, then after chasing through
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1038 that many links, the function just returns what it has even if that is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1039 still a symbolic link.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1040 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1041
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1042 To illustrate the difference between @code{file-chase-links} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1043 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1044 the directory @file{/home/foo}, and @file{/home/foo/hello} is an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1045 ordinary file (or at least, not a symbolic link) or nonexistent. Then
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1046 we would have:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1047
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1048 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1049 (file-chase-links "/usr/foo/hello")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1050 ;; @r{This does not follow the links in the parent directories.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1051 @result{} "/usr/foo/hello"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1052 (file-truename "/usr/foo/hello")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1053 ;; @r{Assuming that @file{/home} is not a symbolic link.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1054 @result{} "/home/foo/hello"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1055 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1056
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1057 @xref{Buffer File Name}, for related information.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1058
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1059 @node File Attributes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1060 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1061 @subsection Other Information about Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1062
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1063 This section describes the functions for getting detailed information
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1064 about a file, other than its contents. This information includes the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1065 mode bits that control access permission, the owner and group numbers,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1066 the number of names, the inode number, the size, and the times of access
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1067 and modification.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1068
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1069 @defun file-modes filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1070 @cindex permission
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1071 @cindex file attributes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1072 This function returns the mode bits of @var{filename}, as an integer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1073 The mode bits are also called the file permissions, and they specify
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1074 access control in the usual Unix fashion. If the low-order bit is 1,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1075 then the file is executable by all users, if the second-lowest-order bit
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1076 is 1, then the file is writable by all users, etc.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1077
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1078 The highest value returnable is 4095 (7777 octal), meaning that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1079 everyone has read, write, and execute permission, that the @acronym{SUID} bit
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1080 is set for both others and group, and that the sticky bit is set.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1081
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1082 If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1083
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1084 This function recursively follows symbolic links at all levels.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1085
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1086 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1087 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1088 (file-modes "~/junk/diffs")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1089 @result{} 492 ; @r{Decimal integer.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1090 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1091 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1092 (format "%o" 492)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1093 @result{} "754" ; @r{Convert to octal.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1094 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1095
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1096 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1097 (set-file-modes "~/junk/diffs" 438)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1098 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1099 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1100
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1101 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1102 (format "%o" 438)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1103 @result{} "666" ; @r{Convert to octal.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1104 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1105
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1106 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1107 % ls -l diffs
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1108 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1109 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1110 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1111 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1112
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1113 If the @var{filename} argument to the next two functions is a symbolic
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1114 link, then these function do @emph{not} replace it with its target.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1115 However, they both recursively follow symbolic links at all levels of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1116 parent directories.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1117
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1118 @defun file-nlinks filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1119 This functions returns the number of names (i.e., hard links) that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1120 file @var{filename} has. If the file does not exist, then this function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1121 returns @code{nil}. Note that symbolic links have no effect on this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1122 function, because they are not considered to be names of the files they
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1123 link to.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1124
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1125 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1126 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1127 % ls -l foo*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1128 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1129 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1130 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1131
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1132 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1133 (file-nlinks "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1134 @result{} 2
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1135 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1136 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1137 (file-nlinks "doesnt-exist")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1138 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1139 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1140 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1141 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1142
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1143 @defun file-attributes filename &optional id-format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1144 @anchor{Definition of file-attributes}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1145 This function returns a list of attributes of file @var{filename}. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1146 the specified file cannot be opened, it returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1147 The optional parameter @var{id-format} specifies the preferred format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1148 of attributes @acronym{UID} and @acronym{GID} (see below)---the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1149 valid values are @code{'string} and @code{'integer}. The latter is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1150 the default, but we plan to change that, so you should specify a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1151 non-@code{nil} value for @var{id-format} if you use the returned
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1152 @acronym{UID} or @acronym{GID}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1153
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1154 The elements of the list, in order, are:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1155
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1156 @enumerate 0
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1157 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1158 @code{t} for a directory, a string for a symbolic link (the name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1159 linked to), or @code{nil} for a text file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1160
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1161 @c Wordy so as to prevent an overfull hbox. --rjc 15mar92
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1162 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1163 The number of names the file has. Alternate names, also known as hard
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1164 links, can be created by using the @code{add-name-to-file} function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1165 (@pxref{Changing Files}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1166
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1167 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1168 The file's @acronym{UID}, normally as a string. However, if it does
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1169 not correspond to a named user, the value is an integer or a floating
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1170 point number.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1171
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1172 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1173 The file's @acronym{GID}, likewise.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1174
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1175 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1176 The time of last access, as a list of two integers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1177 The first integer has the high-order 16 bits of time,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1178 the second has the low 16 bits. (This is similar to the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1179 value of @code{current-time}; see @ref{Time of Day}.)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1180
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1181 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1182 The time of last modification as a list of two integers (as above).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1183 @cindex modification time of file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1184
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1185 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1186 The time of last status change as a list of two integers (as above).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1187
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1188 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1189 The size of the file in bytes. If the size is too large to fit in a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1190 Lisp integer, this is a floating point number.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1191
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1192 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1193 The file's modes, as a string of ten letters or dashes,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1194 as in @samp{ls -l}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1195
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1196 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1197 @code{t} if the file's @acronym{GID} would change if file were
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1198 deleted and recreated; @code{nil} otherwise.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1199
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1200 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1201 The file's inode number. If possible, this is an integer. If the inode
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1202 number is too large to be represented as an integer in Emacs Lisp, then
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1203 the value has the form @code{(@var{high} . @var{low})}, where @var{low}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1204 holds the low 16 bits.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1205
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1206 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1207 The file system number of the file system that the file is in.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1208 Depending on the magnitude of the value, this can be either an integer
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1209 or a cons cell, in the same manner as the inode number. This element
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1210 and the file's inode number together give enough information to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1211 distinguish any two files on the system---no two files can have the same
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1212 values for both of these numbers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1213 @end enumerate
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1214
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1215 For example, here are the file attributes for @file{files.texi}:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1216
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1217 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1218 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1219 (file-attributes "files.texi" 'string)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1220 @result{} (nil 1 "lh" "users"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1221 (8489 20284)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1222 (8489 20284)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1223 (8489 20285)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1224 14906 "-rw-rw-rw-"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1225 nil 129500 -32252)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1226 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1227 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1228
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1229 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1230 and here is how the result is interpreted:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1231
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1232 @table @code
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1233 @item nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1234 is neither a directory nor a symbolic link.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1235
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1236 @item 1
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1237 has only one name (the name @file{files.texi} in the current default
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1238 directory).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1239
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1240 @item "lh"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1241 is owned by the user with name "lh".
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1242
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1243 @item "users"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1244 is in the group with name "users".
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1245
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1246 @item (8489 20284)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1247 was last accessed on Aug 19 00:09.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1248
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1249 @item (8489 20284)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1250 was last modified on Aug 19 00:09.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1251
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1252 @item (8489 20285)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1253 last had its inode changed on Aug 19 00:09.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1254
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1255 @item 14906
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1256 is 14906 bytes long. (It may not contain 14906 characters, though,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1257 if some of the bytes belong to multibyte sequences.)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1258
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1259 @item "-rw-rw-rw-"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1260 has a mode of read and write access for the owner, group, and world.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1261
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1262 @item nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1263 would retain the same @acronym{GID} if it were recreated.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1264
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1265 @item 129500
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1266 has an inode number of 129500.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1267 @item -32252
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1268 is on file system number -32252.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1269 @end table
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1270 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1271
102832
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1272 @cindex MS-DOS and file modes
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1273 @cindex file modes and MS-DOS
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1274 On MS-DOS, there is no such thing as an ``executable'' file mode bit.
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1275 So Emacs considers a file executable if its name ends in one of the
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1276 standard executable extensions, such as @file{.com}, @file{.bat},
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1277 @file{.exe}, and some others. Files that begin with the Unix-standard
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1278 @samp{#!} signature, such as shell and Perl scripts, are also considered
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1279 as executable files. This is reflected in the values returned by
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1280 @code{file-modes} and @code{file-attributes}. Directories are also
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1281 reported with executable bit set, for compatibility with Unix.
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1282
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1283 @node Locating Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1284 @subsection How to Locate Files in Standard Places
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1285 @cindex locate file in path
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1286 @cindex find file in path
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1287
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1288 This section explains how to search for a file in a list of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1289 directories (a @dfn{path}). One example is when you need to look for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1290 a program's executable file, e.g., to find out whether a given program
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1291 is installed on the user's system. Another example is the search for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1292 Lisp libraries (@pxref{Library Search}). Such searches generally need
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1293 to try various possible file name extensions, in addition to various
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1294 possible directories. Emacs provides a function for such a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1295 generalized search for a file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1296
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1297 @defun locate-file filename path &optional suffixes predicate
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1298 This function searches for a file whose name is @var{filename} in a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1299 list of directories given by @var{path}, trying the suffixes in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1300 @var{suffixes}. If it finds such a file, it returns the full
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1301 @dfn{absolute file name} of the file (@pxref{Relative File Names});
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1302 otherwise it returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1303
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1304 The optional argument @var{suffixes} gives the list of file-name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1305 suffixes to append to @var{filename} when searching.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1306 @code{locate-file} tries each possible directory with each of these
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1307 suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1308 are no suffixes, and @var{filename} is used only as-is. Typical
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1309 values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1310 Creation, exec-suffixes}), @code{load-suffixes},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1311 @code{load-file-rep-suffixes} and the return value of the function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1312 @code{get-load-suffixes} (@pxref{Load Suffixes}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1313
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1314 Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1315 Creation, exec-path}) when looking for executable programs or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1316 @code{load-path} (@pxref{Library Search, load-path}) when looking for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1317 Lisp files. If @var{filename} is absolute, @var{path} has no effect,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1318 but the suffixes in @var{suffixes} are still tried.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1319
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1320 The optional argument @var{predicate}, if non-@code{nil}, specifies
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1321 the predicate function to use for testing whether a candidate file is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1322 suitable. The predicate function is passed the candidate file name as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1323 its single argument. If @var{predicate} is @code{nil} or unspecified,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1324 @code{locate-file} uses @code{file-readable-p} as the default
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1325 predicate. Useful non-default predicates include
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1326 @code{file-executable-p}, @code{file-directory-p}, and other
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1327 predicates described in @ref{Kinds of Files}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1328
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1329 For compatibility, @var{predicate} can also be one of the symbols
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1330 @code{executable}, @code{readable}, @code{writable}, @code{exists}, or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1331 a list of one or more of these symbols.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1332 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1333
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1334 @defun executable-find program
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1335 This function searches for the executable file of the named
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1336 @var{program} and returns the full absolute name of the executable,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1337 including its file-name extensions, if any. It returns @code{nil} if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1338 the file is not found. The functions searches in all the directories
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1339 in @code{exec-path} and tries all the file-name extensions in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1340 @code{exec-suffixes}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1341 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1342
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1343 @node Changing Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1344 @section Changing File Names and Attributes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1345 @c @cindex renaming files Duplicates rename-file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1346 @cindex copying files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1347 @cindex deleting files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1348 @cindex linking files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1349 @cindex setting modes of files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1350
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1351 The functions in this section rename, copy, delete, link, and set the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1352 modes of files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1353
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1354 In the functions that have an argument @var{newname}, if a file by the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1355 name of @var{newname} already exists, the actions taken depend on the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1356 value of the argument @var{ok-if-already-exists}:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1357
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1358 @itemize @bullet
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1359 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1360 Signal a @code{file-already-exists} error if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1361 @var{ok-if-already-exists} is @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1362
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1363 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1364 Request confirmation if @var{ok-if-already-exists} is a number.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1365
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1366 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1367 Replace the old file without confirmation if @var{ok-if-already-exists}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1368 is any other value.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1369 @end itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1370
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1371 The next four commands all recursively follow symbolic links at all
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1372 levels of parent directories for their first argument, but, if that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1373 argument is itself a symbolic link, then only @code{copy-file}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1374 replaces it with its (recursive) target.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1375
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1376 @deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1377 @cindex file with multiple names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1378 @cindex file hard link
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1379 This function gives the file named @var{oldname} the additional name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1380 @var{newname}. This means that @var{newname} becomes a new ``hard
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1381 link'' to @var{oldname}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1382
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1383 In the first part of the following example, we list two files,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1384 @file{foo} and @file{foo3}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1385
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1386 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1387 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1388 % ls -li fo*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1389 81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1390 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1391 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1392 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1393
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1394 Now we create a hard link, by calling @code{add-name-to-file}, then list
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1395 the files again. This shows two names for one file, @file{foo} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1396 @file{foo2}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1397
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1398 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1399 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1400 (add-name-to-file "foo" "foo2")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1401 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1402 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1403
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1404 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1405 % ls -li fo*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1406 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1407 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1408 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1409 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1410 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1411
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1412 Finally, we evaluate the following:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1413
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1414 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1415 (add-name-to-file "foo" "foo3" t)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1416 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1417
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1418 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1419 and list the files again. Now there are three names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1420 for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1421 contents of @file{foo3} are lost.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1422
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1423 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1424 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1425 (add-name-to-file "foo1" "foo3")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1426 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1427 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1428
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1429 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1430 % ls -li fo*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1431 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1432 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1433 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1434 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1435 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1436
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1437 This function is meaningless on operating systems where multiple names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1438 for one file are not allowed. Some systems implement multiple names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1439 by copying the file instead.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1440
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1441 See also @code{file-nlinks} in @ref{File Attributes}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1442 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1443
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1444 @deffn Command rename-file filename newname &optional ok-if-already-exists
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1445 This command renames the file @var{filename} as @var{newname}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1446
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1447 If @var{filename} has additional names aside from @var{filename}, it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1448 continues to have those names. In fact, adding the name @var{newname}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1449 with @code{add-name-to-file} and then deleting @var{filename} has the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1450 same effect as renaming, aside from momentary intermediate states.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1451 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1452
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1453 @deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1454 This command copies the file @var{oldname} to @var{newname}. An
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1455 error is signaled if @var{oldname} does not exist. If @var{newname}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1456 names a directory, it copies @var{oldname} into that directory,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1457 preserving its final name component.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1458
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1459 If @var{time} is non-@code{nil}, then this function gives the new file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1460 the same last-modified time that the old one has. (This works on only
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1461 some operating systems.) If setting the time gets an error,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1462 @code{copy-file} signals a @code{file-date-error} error. In an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1463 interactive call, a prefix argument specifies a non-@code{nil} value
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1464 for @var{time}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1465
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1466 This function copies the file modes, too.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1467
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1468 If argument @var{preserve-uid-gid} is @code{nil}, we let the operating
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1469 system decide the user and group ownership of the new file (this is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1470 usually set to the user running Emacs). If @var{preserve-uid-gid} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1471 non-@code{nil}, we attempt to copy the user and group ownership of the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1472 file. This works only on some operating systems, and only if you have
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1473 the correct permissions to do so.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1474 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1475
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1476 @deffn Command make-symbolic-link filename newname &optional ok-if-exists
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1477 @pindex ln
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1478 @kindex file-already-exists
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1479 This command makes a symbolic link to @var{filename}, named
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1480 @var{newname}. This is like the shell command @samp{ln -s
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1481 @var{filename} @var{newname}}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1482
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1483 This function is not available on systems that don't support symbolic
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1484 links.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1485 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1486
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1487 @deffn Command delete-file filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1488 @pindex rm
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1489 This command deletes the file @var{filename}, like the shell command
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1490 @samp{rm @var{filename}}. If the file has multiple names, it continues
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1491 to exist under the other names.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1492
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1493 A suitable kind of @code{file-error} error is signaled if the file does
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1494 not exist, or is not deletable. (On Unix and GNU/Linux, a file is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1495 deletable if its directory is writable.)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1496
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1497 If @var{filename} is a symbolic link, @code{delete-file} does not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1498 replace it with its target, but it does follow symbolic links at all
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1499 levels of parent directories.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1500
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1501 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1502 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1503
98831
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1504 @deffn Command set-file-modes filename mode
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1505 This function sets mode bits of @var{filename} to @var{mode} (which
98831
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1506 must be an integer when the function is called non-interactively).
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1507 Only the low 12 bits of @var{mode} are used.
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1508
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1509 Interactively, @var{mode} is read from the minibuffer using
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1510 @code{read-file-modes}, which accepts mode bits either as a number or
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1511 as a character string representing the mode bits symbolically. See
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1512 the description of @code{read-file-modes} below for the supported
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1513 forms of symbolic notation for mode bits.
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1514
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1515 This function recursively follows symbolic links at all levels for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1516 @var{filename}.
98831
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1517 @end deffn
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1518
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1519 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1520 @defun set-default-file-modes mode
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1521 @cindex umask
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1522 This function sets the default file protection for new files created by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1523 Emacs and its subprocesses. Every file created with Emacs initially has
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1524 this protection, or a subset of it (@code{write-region} will not give a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1525 file execute permission even if the default file protection allows
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1526 execute permission). On Unix and GNU/Linux, the default protection is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1527 the bitwise complement of the ``umask'' value.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1528
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1529 The argument @var{mode} must be an integer. On most systems, only the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1530 low 9 bits of @var{mode} are meaningful. You can use the Lisp construct
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1531 for octal character codes to enter @var{mode}; for example,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1532
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1533 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1534 (set-default-file-modes ?\644)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1535 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1536
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1537 Saving a modified version of an existing file does not count as creating
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1538 the file; it preserves the existing file's mode, whatever that is. So
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1539 the default file protection has no effect.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1540 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1541
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1542 @defun default-file-modes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1543 This function returns the current default protection value.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1544 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1545
98831
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1546 @defun read-file-modes &optional prompt base-file
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1547 This function reads file mode bits from the minibuffer. The optional
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1548 argument @var{prompt} specifies a non-default prompt. Second optional
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1549 argument @var{base-file} is the name of a file on whose permissions to
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1550 base the mode bits that this function returns, if what the user types
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1551 specifies mode bits relative to permissions of an existing file.
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1552
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1553 If user input represents an octal number, this function returns that
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1554 number. If it is a complete symbolic specification of mode bits, as
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1555 in @code{"u=rwx"}, the function converts it to the equivalent numeric
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1556 value using @code{file-modes-symbolic-to-number} and returns the
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1557 result. If the specification is relative, as in @code{"o+g"}, then
98841
b7164f9c80bc (Changing Files): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents: 98831
diff changeset
1558 the permissions on which the specification is based are taken from the
98831
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1559 mode bits of @var{base-file}. If @var{base-file} is omitted or
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1560 @code{nil}, the function uses @code{0} as the base mode bits. The
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1561 complete and relative specifications can be combined, as in
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1562 @code{"u+r,g+rx,o+r,g-w"}. @xref{File Permissions,,, coreutils, The
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1563 @sc{gnu} @code{Coreutils} Manual}, for detailed description of
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1564 symbolic mode bits specifications.
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1565 @end defun
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1566
98927
b5ddab370f08 Don't use @deffn Subroutine.
Eli Zaretskii <eliz@gnu.org>
parents: 98841
diff changeset
1567 @defun file-modes-symbolic-to-number modes &optional base-modes
98831
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1568 This subroutine converts a symbolic specification of file mode bits in
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1569 @var{modes} into the equivalent numeric value. If the symbolic
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1570 specification is based on an existing file, that file's mode bits are
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1571 taken from the optional argument @var{base-modes}; if that argument is
99912
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
1572 omitted or @code{nil}, it defaults to zero, i.e.@: no access rights at
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
1573 all.
98927
b5ddab370f08 Don't use @deffn Subroutine.
Eli Zaretskii <eliz@gnu.org>
parents: 98841
diff changeset
1574 @end defun
98831
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1575
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1576 @defun set-file-times filename &optional time
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1577 This function sets the access and modification times of @var{filename}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1578 to @var{time}. The return value is @code{t} if the times are successfully
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1579 set, otherwise it is @code{nil}. @var{time} defaults to the current
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1580 time and must be in the format returned by @code{current-time}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1581 (@pxref{Time of Day}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1582 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1583
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1584 @node File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1585 @section File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1586 @cindex file names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1587
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1588 Files are generally referred to by their names, in Emacs as elsewhere.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1589 File names in Emacs are represented as strings. The functions that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1590 operate on a file all expect a file name argument.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1591
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1592 In addition to operating on files themselves, Emacs Lisp programs
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1593 often need to operate on file names; i.e., to take them apart and to use
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1594 part of a name to construct related file names. This section describes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1595 how to manipulate file names.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1596
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1597 The functions in this section do not actually access files, so they
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1598 can operate on file names that do not refer to an existing file or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1599 directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1600
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1601 On MS-DOS and MS-Windows, these functions (like the function that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1602 actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1603 where backslashes separate the components, as well as Unix syntax; but
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1604 they always return Unix syntax. This enables Lisp programs to specify
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1605 file names in Unix syntax and work properly on all systems without
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1606 change.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1607
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1608 @menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1609 * File Name Components:: The directory part of a file name, and the rest.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1610 * Relative File Names:: Some file names are relative to a current directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1611 * Directory Names:: A directory's name as a directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1612 is different from its name as a file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1613 * File Name Expansion:: Converting relative file names to absolute ones.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1614 * Unique File Names:: Generating names for temporary files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1615 * File Name Completion:: Finding the completions for a given file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1616 * Standard File Names:: If your package uses a fixed file name,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1617 how to handle various operating systems simply.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1618 @end menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1619
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1620 @node File Name Components
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1621 @subsection File Name Components
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1622 @cindex directory part (of file name)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1623 @cindex nondirectory part (of file name)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1624 @cindex version number (in file name)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1625
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1626 The operating system groups files into directories. To specify a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1627 file, you must specify the directory and the file's name within that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1628 directory. Therefore, Emacs considers a file name as having two main
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1629 parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1630 (or @dfn{file name within the directory}). Either part may be empty.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1631 Concatenating these two parts reproduces the original file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1632
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1633 On most systems, the directory part is everything up to and including
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1634 the last slash (backslash is also allowed in input on MS-DOS or
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1635 MS-Windows); the nondirectory part is the rest.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1636
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1637 For some purposes, the nondirectory part is further subdivided into
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1638 the name proper and the @dfn{version number}. On most systems, only
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1639 backup files have version numbers in their names.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1640
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1641 @defun file-name-directory filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1642 This function returns the directory part of @var{filename}, as a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1643 directory name (@pxref{Directory Names}), or @code{nil} if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1644 @var{filename} does not include a directory part.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1645
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1646 On GNU and Unix systems, a string returned by this function always
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1647 ends in a slash. On MS-DOS it can also end in a colon.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1648
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1649 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1650 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1651 (file-name-directory "lewis/foo") ; @r{Unix example}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1652 @result{} "lewis/"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1653 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1654 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1655 (file-name-directory "foo") ; @r{Unix example}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1656 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1657 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1658 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1659 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1660
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1661 @defun file-name-nondirectory filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1662 This function returns the nondirectory part of @var{filename}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1663
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1664 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1665 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1666 (file-name-nondirectory "lewis/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1667 @result{} "foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1668 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1669 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1670 (file-name-nondirectory "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1671 @result{} "foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1672 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1673 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1674 (file-name-nondirectory "lewis/")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1675 @result{} ""
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1676 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1677 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1678 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1679
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1680 @defun file-name-sans-versions filename &optional keep-backup-version
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1681 This function returns @var{filename} with any file version numbers,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1682 backup version numbers, or trailing tildes discarded.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1683
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1684 If @var{keep-backup-version} is non-@code{nil}, then true file version
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1685 numbers understood as such by the file system are discarded from the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1686 return value, but backup version numbers are kept.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1687
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1688 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1689 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1690 (file-name-sans-versions "~rms/foo.~1~")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1691 @result{} "~rms/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1692 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1693 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1694 (file-name-sans-versions "~rms/foo~")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1695 @result{} "~rms/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1696 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1697 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1698 (file-name-sans-versions "~rms/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1699 @result{} "~rms/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1700 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1701 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1702 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1703
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1704 @defun file-name-extension filename &optional period
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1705 This function returns @var{filename}'s final ``extension,'' if any,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1706 after applying @code{file-name-sans-versions} to remove any
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1707 version/backup part. The extension, in a file name, is the part that
99526
5e92b1aa0a1d (File Name Components): Fix file-name-extension documentation.
Lute Kamstra <lute@gnu.org>
parents: 99477
diff changeset
1708 follows the last @samp{.} in the last name component (minus any
5e92b1aa0a1d (File Name Components): Fix file-name-extension documentation.
Lute Kamstra <lute@gnu.org>
parents: 99477
diff changeset
1709 version/backup part).
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1710
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1711 This function returns @code{nil} for extensionless file names such as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1712 @file{foo}. It returns @code{""} for null extensions, as in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1713 @file{foo.}. If the last component of a file name begins with a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1714 @samp{.}, that @samp{.} doesn't count as the beginning of an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1715 extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1716 @samp{.emacs}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1717
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1718 If @var{period} is non-@code{nil}, then the returned value includes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1719 the period that delimits the extension, and if @var{filename} has no
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1720 extension, the value is @code{""}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1721 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1722
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1723 @defun file-name-sans-extension filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1724 This function returns @var{filename} minus its extension, if any. The
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1725 version/backup part, if present, is only removed if the file has an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1726 extension. For example,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1727
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1728 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1729 (file-name-sans-extension "foo.lose.c")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1730 @result{} "foo.lose"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1731 (file-name-sans-extension "big.hack/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1732 @result{} "big.hack/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1733 (file-name-sans-extension "/my/home/.emacs")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1734 @result{} "/my/home/.emacs"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1735 (file-name-sans-extension "/my/home/.emacs.el")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1736 @result{} "/my/home/.emacs"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1737 (file-name-sans-extension "~/foo.el.~3~")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1738 @result{} "~/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1739 (file-name-sans-extension "~/foo.~3~")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1740 @result{} "~/foo.~3~"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1741 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1742
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1743 Note that the @samp{.~3~} in the two last examples is the backup part,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1744 not an extension.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1745 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1746
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1747 @ignore
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1748 Andrew Innes says that this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1749
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1750 @c @defvar directory-sep-char
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1751 This variable holds the character that Emacs normally uses to separate
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1752 file name components. The default value is @code{?/}, but on MS-Windows
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1753 you can set it to @code{?\\}; then the functions that transform file names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1754 use backslashes in their output.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1755
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1756 File names using backslashes work as input to Lisp primitives even on
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1757 MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1758 value of @code{?/}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1759 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1760 @end ignore
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1761
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1762 @node Relative File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1763 @subsection Absolute and Relative File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1764 @cindex absolute file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1765 @cindex relative file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1766
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1767 All the directories in the file system form a tree starting at the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1768 root directory. A file name can specify all the directory names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1769 starting from the root of the tree; then it is called an @dfn{absolute}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1770 file name. Or it can specify the position of the file in the tree
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1771 relative to a default directory; then it is called a @dfn{relative} file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1772 name. On Unix and GNU/Linux, an absolute file name starts with a slash
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1773 or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1774 MS-Windows, an absolute file name starts with a slash or a backslash, or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1775 with a drive specification @samp{@var{x}:/}, where @var{x} is the
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1776 @dfn{drive letter}.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1777
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1778 @defun file-name-absolute-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1779 This function returns @code{t} if file @var{filename} is an absolute
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1780 file name, @code{nil} otherwise.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1781
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1782 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1783 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1784 (file-name-absolute-p "~rms/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1785 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1786 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1787 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1788 (file-name-absolute-p "rms/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1789 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1790 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1791 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1792 (file-name-absolute-p "/user/rms/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1793 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1794 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1795 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1796 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1797
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1798 Given a possibly relative file name, you can convert it to an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1799 absolute name using @code{expand-file-name} (@pxref{File Name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1800 Expansion}). This function converts absolute file names to relative
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1801 names:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1802
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1803 @defun file-relative-name filename &optional directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1804 This function tries to return a relative name that is equivalent to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1805 @var{filename}, assuming the result will be interpreted relative to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1806 @var{directory} (an absolute directory name or directory file name).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1807 If @var{directory} is omitted or @code{nil}, it defaults to the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1808 current buffer's default directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1809
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1810 On some operating systems, an absolute file name begins with a device
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1811 name. On such systems, @var{filename} has no relative equivalent based
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1812 on @var{directory} if they start with two different device names. In
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1813 this case, @code{file-relative-name} returns @var{filename} in absolute
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1814 form.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1815
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1816 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1817 (file-relative-name "/foo/bar" "/foo/")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1818 @result{} "bar"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1819 (file-relative-name "/foo/bar" "/hack/")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1820 @result{} "../foo/bar"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1821 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1822 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1823
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1824 @node Directory Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1825 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1826 @subsection Directory Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1827 @cindex directory name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1828 @cindex file name of directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1829
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1830 A @dfn{directory name} is the name of a directory. A directory is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1831 actually a kind of file, so it has a file name, which is related to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1832 the directory name but not identical to it. (This is not quite the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1833 same as the usual Unix terminology.) These two different names for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1834 the same entity are related by a syntactic transformation. On GNU and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1835 Unix systems, this is simple: a directory name ends in a slash,
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1836 whereas the directory's name as a file lacks that slash. On MS-DOS
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1837 the relationship is more complicated.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1838
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1839 The difference between a directory name and its name as a file is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1840 subtle but crucial. When an Emacs variable or function argument is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1841 described as being a directory name, a file name of a directory is not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1842 acceptable. When @code{file-name-directory} returns a string, that is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1843 always a directory name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1844
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1845 The following two functions convert between directory names and file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1846 names. They do nothing special with environment variable substitutions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1847 such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1848
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1849 @defun file-name-as-directory filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1850 This function returns a string representing @var{filename} in a form
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1851 that the operating system will interpret as the name of a directory. On
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1852 most systems, this means appending a slash to the string (if it does not
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1853 already end in one).
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1854
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1855 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1856 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1857 (file-name-as-directory "~rms/lewis")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1858 @result{} "~rms/lewis/"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1859 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1860 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1861 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1862
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1863 @defun directory-file-name dirname
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1864 This function returns a string representing @var{dirname} in a form that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1865 the operating system will interpret as the name of a file. On most
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1866 systems, this means removing the final slash (or backslash) from the
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1867 string.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1868
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1869 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1870 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1871 (directory-file-name "~lewis/")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1872 @result{} "~lewis"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1873 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1874 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1875 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1876
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1877 Given a directory name, you can combine it with a relative file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1878 using @code{concat}:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1879
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1880 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1881 (concat @var{dirname} @var{relfile})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1882 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1883
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1884 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1885 Be sure to verify that the file name is relative before doing that.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1886 If you use an absolute file name, the results could be syntactically
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1887 invalid or refer to the wrong file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1888
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1889 If you want to use a directory file name in making such a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1890 combination, you must first convert it to a directory name using
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1891 @code{file-name-as-directory}:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1892
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1893 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1894 (concat (file-name-as-directory @var{dirfile}) @var{relfile})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1895 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1896
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1897 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1898 Don't try concatenating a slash by hand, as in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1899
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1900 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1901 ;;; @r{Wrong!}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1902 (concat @var{dirfile} "/" @var{relfile})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1903 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1904
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1905 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1906 because this is not portable. Always use
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1907 @code{file-name-as-directory}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1908
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1909 @cindex directory name abbreviation
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1910 Directory name abbreviations are useful for directories that are
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1911 normally accessed through symbolic links. Sometimes the users recognize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1912 primarily the link's name as ``the name'' of the directory, and find it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1913 annoying to see the directory's ``real'' name. If you define the link
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1914 name as an abbreviation for the ``real'' name, Emacs shows users the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1915 abbreviation instead.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1916
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1917 @defvar directory-abbrev-alist
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1918 The variable @code{directory-abbrev-alist} contains an alist of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1919 abbreviations to use for file directories. Each element has the form
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1920 @code{(@var{from} . @var{to})}, and says to replace @var{from} with
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1921 @var{to} when it appears in a directory name. The @var{from} string is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1922 actually a regular expression; it should always start with @samp{^}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1923 The @var{to} string should be an ordinary absolute directory name. Do
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1924 not use @samp{~} to stand for a home directory in that string. The
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1925 function @code{abbreviate-file-name} performs these substitutions.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1926
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1927 You can set this variable in @file{site-init.el} to describe the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1928 abbreviations appropriate for your site.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1929
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1930 Here's an example, from a system on which file system @file{/home/fsf}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1931 and so on are normally accessed through symbolic links named @file{/fsf}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1932 and so on.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1933
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1934 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1935 (("^/home/fsf" . "/fsf")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1936 ("^/home/gp" . "/gp")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1937 ("^/home/gd" . "/gd"))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1938 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1939 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1940
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1941 To convert a directory name to its abbreviation, use this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1942 function:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1943
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1944 @defun abbreviate-file-name filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1945 @anchor{Definition of abbreviate-file-name}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1946 This function applies abbreviations from @code{directory-abbrev-alist}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1947 to its argument, and substitutes @samp{~} for the user's home
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1948 directory. You can use it for directory names and for file names,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1949 because it recognizes abbreviations even as part of the name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1950 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1951
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1952 @node File Name Expansion
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1953 @subsection Functions that Expand Filenames
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1954 @cindex expansion of file names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1955
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1956 @dfn{Expansion} of a file name means converting a relative file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1957 to an absolute one. Since this is done relative to a default directory,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1958 you must specify the default directory name as well as the file name to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1959 be expanded. Expansion also simplifies file names by eliminating
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1960 redundancies such as @file{./} and @file{@var{name}/../}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1961
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1962 @defun expand-file-name filename &optional directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1963 This function converts @var{filename} to an absolute file name. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1964 @var{directory} is supplied, it is the default directory to start with
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1965 if @var{filename} is relative. (The value of @var{directory} should
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1966 itself be an absolute directory name or directory file name; it may
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1967 start with @samp{~}.) Otherwise, the current buffer's value of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1968 @code{default-directory} is used. For example:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1969
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1970 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1971 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1972 (expand-file-name "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1973 @result{} "/xcssun/users/rms/lewis/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1974 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1975 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1976 (expand-file-name "../foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1977 @result{} "/xcssun/users/rms/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1978 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1979 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1980 (expand-file-name "foo" "/usr/spool/")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1981 @result{} "/usr/spool/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1982 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1983 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1984 (expand-file-name "$HOME/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1985 @result{} "/xcssun/users/rms/lewis/$HOME/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1986 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1987 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1988
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1989 If the part of the combined file name before the first slash is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1990 @samp{~}, it expands to the value of the @env{HOME} environment
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1991 variable (usually your home directory). If the part before the first
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1992 slash is @samp{~@var{user}} and if @var{user} is a valid login name,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1993 it expands to @var{user}'s home directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1994
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1995 Filenames containing @samp{.} or @samp{..} are simplified to their
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1996 canonical form:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1997
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1998 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1999 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2000 (expand-file-name "bar/../foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2001 @result{} "/xcssun/users/rms/lewis/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2002 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2003 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2004
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2005 In some cases, a leading @samp{..} component can remain in the output:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2006
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2007 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2008 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2009 (expand-file-name "../home" "/")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2010 @result{} "/../home"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2011 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2012 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2013
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2014 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2015 This is for the sake of filesystems that have the concept of a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2016 ``superroot'' above the root directory @file{/}. On other filesystems,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2017 @file{/../} is interpreted exactly the same as @file{/}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2018
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2019 Note that @code{expand-file-name} does @emph{not} expand environment
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2020 variables; only @code{substitute-in-file-name} does that.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2021
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2022 Note also that @code{expand-file-name} does not follow symbolic links
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2023 at any level. This results in a difference between the way
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2024 @code{file-truename} and @code{expand-file-name} treat @samp{..}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2025 Assuming that @samp{/tmp/bar} is a symbolic link to the directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2026 @samp{/tmp/foo/bar} we get:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2027
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2028 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2029 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2030 (file-truename "/tmp/bar/../myfile")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2031 @result{} "/tmp/foo/myfile"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2032 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2033 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2034 (expand-file-name "/tmp/bar/../myfile")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2035 @result{} "/tmp/myfile"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2036 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2037 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2038
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2039 If you may need to follow symbolic links preceding @samp{..}, you
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2040 should make sure to call @code{file-truename} without prior direct or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2041 indirect calls to @code{expand-file-name}. @xref{Truenames}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2042 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2043
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2044 @defvar default-directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2045 The value of this buffer-local variable is the default directory for the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2046 current buffer. It should be an absolute directory name; it may start
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2047 with @samp{~}. This variable is buffer-local in every buffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2048
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2049 @code{expand-file-name} uses the default directory when its second
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2050 argument is @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2051
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
2052 The value is always a string ending with a slash.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2053
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2054 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2055 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2056 default-directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2057 @result{} "/user/lewis/manual/"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2058 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2059 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2060 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2061
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2062 @defun substitute-in-file-name filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2063 @anchor{Definition of substitute-in-file-name}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2064 This function replaces environment variable references in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2065 @var{filename} with the environment variable values. Following
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2066 standard Unix shell syntax, @samp{$} is the prefix to substitute an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2067 environment variable value. If the input contains @samp{$$}, that is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2068 converted to @samp{$}; this gives the user a way to ``quote'' a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2069 @samp{$}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2070
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2071 The environment variable name is the series of alphanumeric characters
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2072 (including underscores) that follow the @samp{$}. If the character following
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2073 the @samp{$} is a @samp{@{}, then the variable name is everything up to the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2074 matching @samp{@}}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2075
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2076 Calling @code{substitute-in-file-name} on output produced by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2077 @code{substitute-in-file-name} tends to give incorrect results. For
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2078 instance, use of @samp{$$} to quote a single @samp{$} won't work
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2079 properly, and @samp{$} in an environment variable's value could lead
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2080 to repeated substitution. Therefore, programs that call this function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2081 and put the output where it will be passed to this function need to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2082 double all @samp{$} characters to prevent subsequent incorrect
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2083 results.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2084
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2085 @c Wordy to avoid overfull hbox. --rjc 15mar92
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2086 Here we assume that the environment variable @code{HOME}, which holds
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2087 the user's home directory name, has value @samp{/xcssun/users/rms}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2088
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2089 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2090 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2091 (substitute-in-file-name "$HOME/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2092 @result{} "/xcssun/users/rms/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2093 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2094 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2095
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2096 After substitution, if a @samp{~} or a @samp{/} appears immediately
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2097 after another @samp{/}, the function discards everything before it (up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2098 through the immediately preceding @samp{/}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2099
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2100 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2101 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2102 (substitute-in-file-name "bar/~/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2103 @result{} "~/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2104 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2105 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2106 (substitute-in-file-name "/usr/local/$HOME/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2107 @result{} "/xcssun/users/rms/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2108 ;; @r{@file{/usr/local/} has been discarded.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2109 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2110 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2111
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2112 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2113
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2114 @node Unique File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2115 @subsection Generating Unique File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2116
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2117 Some programs need to write temporary files. Here is the usual way to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2118 construct a name for such a file:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2119
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2120 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2121 (make-temp-file @var{name-of-application})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2122 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2123
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2124 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2125 The job of @code{make-temp-file} is to prevent two different users or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2126 two different jobs from trying to use the exact same file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2127
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2128 @defun make-temp-file prefix &optional dir-flag suffix
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2129 This function creates a temporary file and returns its name. Emacs
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2130 creates the temporary file's name by adding to @var{prefix} some
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2131 random characters that are different in each Emacs job. The result is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2132 guaranteed to be a newly created empty file. On MS-DOS, this function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2133 can truncate the @var{string} prefix to fit into the 8+3 file-name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2134 limits. If @var{prefix} is a relative file name, it is expanded
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2135 against @code{temporary-file-directory}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2136
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2137 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2138 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2139 (make-temp-file "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2140 @result{} "/tmp/foo232J6v"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2141 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2142 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2143
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2144 When @code{make-temp-file} returns, the file has been created and is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2145 empty. At that point, you should write the intended contents into the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2146 file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2147
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2148 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2149 empty directory instead of an empty file. It returns the file name,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2150 not the directory name, of that directory. @xref{Directory Names}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2151
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2152 If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2153 the end of the file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2154
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2155 To prevent conflicts among different libraries running in the same
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2156 Emacs, each Lisp program that uses @code{make-temp-file} should have its
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2157 own @var{prefix}. The number added to the end of @var{prefix}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2158 distinguishes between the same application running in different Emacs
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2159 jobs. Additional added characters permit a large number of distinct
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2160 names even in one Emacs job.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2161 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2162
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2163 The default directory for temporary files is controlled by the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2164 variable @code{temporary-file-directory}. This variable gives the user
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2165 a uniform way to specify the directory for all temporary files. Some
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2166 programs use @code{small-temporary-file-directory} instead, if that is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2167 non-@code{nil}. To use it, you should expand the prefix against
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2168 the proper directory before calling @code{make-temp-file}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2169
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2170 In older Emacs versions where @code{make-temp-file} does not exist,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2171 you should use @code{make-temp-name} instead:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2172
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2173 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2174 (make-temp-name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2175 (expand-file-name @var{name-of-application}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2176 temporary-file-directory))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2177 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2178
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2179 @defun make-temp-name string
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2180 This function generates a string that can be used as a unique file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2181 name. The name starts with @var{string}, and has several random
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2182 characters appended to it, which are different in each Emacs job. It
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2183 is like @code{make-temp-file} except that it just constructs a name,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2184 and does not create a file. Another difference is that @var{string}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2185 should be an absolute file name. On MS-DOS, this function can
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2186 truncate the @var{string} prefix to fit into the 8+3 file-name limits.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2187 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2188
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2189 @defvar temporary-file-directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2190 @cindex @code{TMPDIR} environment variable
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2191 @cindex @code{TMP} environment variable
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2192 @cindex @code{TEMP} environment variable
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2193 This variable specifies the directory name for creating temporary files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2194 Its value should be a directory name (@pxref{Directory Names}), but it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2195 is good for Lisp programs to cope if the value is a directory's file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2196 name instead. Using the value as the second argument to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2197 @code{expand-file-name} is a good way to achieve that.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2198
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2199 The default value is determined in a reasonable way for your operating
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2200 system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2201 environment variables, with a fall-back to a system-dependent name if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2202 none of these variables is defined.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2203
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2204 Even if you do not use @code{make-temp-file} to create the temporary
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2205 file, you should still use this variable to decide which directory to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2206 put the file in. However, if you expect the file to be small, you
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2207 should use @code{small-temporary-file-directory} first if that is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2208 non-@code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2209 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2210
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2211 @defvar small-temporary-file-directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2212 This variable specifies the directory name for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2213 creating certain temporary files, which are likely to be small.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2214
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2215 If you want to write a temporary file which is likely to be small, you
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2216 should compute the directory like this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2217
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2218 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2219 (make-temp-file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2220 (expand-file-name @var{prefix}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2221 (or small-temporary-file-directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2222 temporary-file-directory)))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2223 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2224 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2225
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2226 @node File Name Completion
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2227 @subsection File Name Completion
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2228 @cindex file name completion subroutines
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2229 @cindex completion, file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2230
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2231 This section describes low-level subroutines for completing a file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2232 name. For higher level functions, see @ref{Reading File Names}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2233
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2234 @defun file-name-all-completions partial-filename directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2235 This function returns a list of all possible completions for a file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2236 whose name starts with @var{partial-filename} in directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2237 @var{directory}. The order of the completions is the order of the files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2238 in the directory, which is unpredictable and conveys no useful
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2239 information.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2240
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2241 The argument @var{partial-filename} must be a file name containing no
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2242 directory part and no slash (or backslash on some systems). The current
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2243 buffer's default directory is prepended to @var{directory}, if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2244 @var{directory} is not absolute.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2245
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2246 In the following example, suppose that @file{~rms/lewis} is the current
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2247 default directory, and has five files whose names begin with @samp{f}:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2248 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2249 @file{file.c.~2~}.@refill
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2250
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2251 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2252 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2253 (file-name-all-completions "f" "")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2254 @result{} ("foo" "file~" "file.c.~2~"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2255 "file.c.~1~" "file.c")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2256 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2257
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2258 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2259 (file-name-all-completions "fo" "")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2260 @result{} ("foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2261 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2262 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2263 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2264
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2265 @defun file-name-completion filename directory &optional predicate
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2266 This function completes the file name @var{filename} in directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2267 @var{directory}. It returns the longest prefix common to all file names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2268 in directory @var{directory} that start with @var{filename}. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2269 @var{predicate} is non-@code{nil} then it ignores possible completions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2270 that don't satisfy @var{predicate}, after calling that function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2271 with one argument, the expanded absolute file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2272
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2273 If only one match exists and @var{filename} matches it exactly, the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2274 function returns @code{t}. The function returns @code{nil} if directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2275 @var{directory} contains no name starting with @var{filename}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2276
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2277 In the following example, suppose that the current default directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2278 has five files whose names begin with @samp{f}: @file{foo},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2279 @file{file~}, @file{file.c}, @file{file.c.~1~}, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2280 @file{file.c.~2~}.@refill
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2281
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2282 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2283 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2284 (file-name-completion "fi" "")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2285 @result{} "file"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2286 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2287
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2288 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2289 (file-name-completion "file.c.~1" "")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2290 @result{} "file.c.~1~"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2291 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2292
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2293 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2294 (file-name-completion "file.c.~1~" "")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2295 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2296 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2297
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2298 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2299 (file-name-completion "file.c.~3" "")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2300 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2301 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2302 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2303 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2304
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2305 @defopt completion-ignored-extensions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2306 @code{file-name-completion} usually ignores file names that end in any
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2307 string in this list. It does not ignore them when all the possible
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2308 completions end in one of these suffixes. This variable has no effect
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2309 on @code{file-name-all-completions}.@refill
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2310
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2311 A typical value might look like this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2312
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2313 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2314 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2315 completion-ignored-extensions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2316 @result{} (".o" ".elc" "~" ".dvi")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2317 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2318 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2319
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2320 If an element of @code{completion-ignored-extensions} ends in a slash
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2321 @samp{/}, it signals a directory. The elements which do @emph{not} end
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2322 in a slash will never match a directory; thus, the above value will not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2323 filter out a directory named @file{foo.elc}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2324 @end defopt
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2325
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2326 @node Standard File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2327 @subsection Standard File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2328
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2329 Most of the file names used in Lisp programs are entered by the user.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2330 But occasionally a Lisp program needs to specify a standard file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2331 for a particular use---typically, to hold customization information
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2332 about each user. For example, abbrev definitions are stored (by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2333 default) in the file @file{~/.abbrev_defs}; the @code{completion}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2334 package stores completions in the file @file{~/.completions}. These are
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2335 two of the many standard file names used by parts of Emacs for certain
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2336 purposes.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2337
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2338 Various operating systems have their own conventions for valid file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2339 names and for which file names to use for user profile data. A Lisp
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2340 program which reads a file using a standard file name ought to use, on
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2341 each type of system, a file name suitable for that system. The function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2342 @code{convert-standard-filename} makes this easy to do.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2343
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2344 @defun convert-standard-filename filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2345 This function alters the file name @var{filename} to fit the conventions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2346 of the operating system in use, and returns the result as a new string.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2347 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2348
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2349 The recommended way to specify a standard file name in a Lisp program
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2350 is to choose a name which fits the conventions of GNU and Unix systems,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2351 usually with a nondirectory part that starts with a period, and pass it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2352 to @code{convert-standard-filename} instead of using it directly. Here
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2353 is an example from the @code{completion} package:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2354
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2355 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2356 (defvar save-completions-file-name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2357 (convert-standard-filename "~/.completions")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2358 "*The file name to save completions to.")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2359 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2360
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2361 On GNU and Unix systems, and on some other systems as well,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2362 @code{convert-standard-filename} returns its argument unchanged. On
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2363 some other systems, it alters the name to fit the system's conventions.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2364
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2365 For example, on MS-DOS the alterations made by this function include
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2366 converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2367 middle of the name to @samp{.} if there is no other @samp{.}, inserting
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2368 a @samp{.} after eight characters if there is none, and truncating to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2369 three characters after the @samp{.}. (It makes other changes as well.)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2370 Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2371 @file{.completions} becomes @file{_complet.ion}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2372
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2373 @node Contents of Directories
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2374 @section Contents of Directories
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2375 @cindex directory-oriented functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2376 @cindex file names in directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2377
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2378 A directory is a kind of file that contains other files entered under
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2379 various names. Directories are a feature of the file system.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2380
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2381 Emacs can list the names of the files in a directory as a Lisp list,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2382 or display the names in a buffer using the @code{ls} shell command. In
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2383 the latter case, it can optionally display information about each file,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2384 depending on the options passed to the @code{ls} command.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2385
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2386 @defun directory-files directory &optional full-name match-regexp nosort
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2387 This function returns a list of the names of the files in the directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2388 @var{directory}. By default, the list is in alphabetical order.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2389
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2390 If @var{full-name} is non-@code{nil}, the function returns the files'
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2391 absolute file names. Otherwise, it returns the names relative to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2392 the specified directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2393
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2394 If @var{match-regexp} is non-@code{nil}, this function returns only
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2395 those file names that contain a match for that regular expression---the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2396 other file names are excluded from the list. On case-insensitive
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2397 filesystems, the regular expression matching is case-insensitive.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2398
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2399 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2400 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2401 the list, so you get the file names in no particular order. Use this if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2402 you want the utmost possible speed and don't care what order the files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2403 are processed in. If the order of processing is visible to the user,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2404 then the user will probably be happier if you do sort the names.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2405
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2406 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2407 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2408 (directory-files "~lewis")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2409 @result{} ("#foo#" "#foo.el#" "." ".."
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2410 "dired-mods.el" "files.texi"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2411 "files.texi.~1~")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2412 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2413 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2414
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2415 An error is signaled if @var{directory} is not the name of a directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2416 that can be read.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2417 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2418
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2419 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2420 This is similar to @code{directory-files} in deciding which files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2421 to report on and how to report their names. However, instead
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2422 of returning a list of file names, it returns for each file a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2423 list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2424 is what @code{file-attributes} would return for that file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2425 The optional argument @var{id-format} has the same meaning as the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2426 corresponding argument to @code{file-attributes} (@pxref{Definition
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2427 of file-attributes}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2428 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2429
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2430 @defun file-expand-wildcards pattern &optional full
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2431 This function expands the wildcard pattern @var{pattern}, returning
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2432 a list of file names that match it.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2433
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2434 If @var{pattern} is written as an absolute file name,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2435 the values are absolute also.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2436
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2437 If @var{pattern} is written as a relative file name, it is interpreted
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2438 relative to the current default directory. The file names returned are
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2439 normally also relative to the current default directory. However, if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2440 @var{full} is non-@code{nil}, they are absolute.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2441 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2442
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2443 @defun insert-directory file switches &optional wildcard full-directory-p
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2444 This function inserts (in the current buffer) a directory listing for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2445 directory @var{file}, formatted with @code{ls} according to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2446 @var{switches}. It leaves point after the inserted text.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2447 @var{switches} may be a string of options, or a list of strings
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2448 representing individual options.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2449
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2450 The argument @var{file} may be either a directory name or a file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2451 specification including wildcard characters. If @var{wildcard} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2452 non-@code{nil}, that means treat @var{file} as a file specification with
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2453 wildcards.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2454
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2455 If @var{full-directory-p} is non-@code{nil}, that means the directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2456 listing is expected to show the full contents of a directory. You
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2457 should specify @code{t} when @var{file} is a directory and switches do
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2458 not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2459 describe a directory itself as a file, rather than showing its
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2460 contents.)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2461
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2462 On most systems, this function works by running a directory listing
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2463 program whose name is in the variable @code{insert-directory-program}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2464 If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2465 @code{shell-file-name}, to expand the wildcards.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2466
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2467 MS-DOS and MS-Windows systems usually lack the standard Unix program
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2468 @code{ls}, so this function emulates the standard Unix program @code{ls}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2469 with Lisp code.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2470
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2471 As a technical detail, when @var{switches} contains the long
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2472 @samp{--dired} option, @code{insert-directory} treats it specially,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2473 for the sake of dired. However, the normally equivalent short
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2474 @samp{-D} option is just passed on to @code{insert-directory-program},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2475 as any other option.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2476 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2477
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2478 @defvar insert-directory-program
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2479 This variable's value is the program to run to generate a directory listing
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2480 for the function @code{insert-directory}. It is ignored on systems
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2481 which generate the listing with Lisp code.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2482 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2483
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2484 @node Create/Delete Dirs
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2485 @section Creating and Deleting Directories
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2486 @cindex creating and deleting directories
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2487 @c Emacs 19 features
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2488
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2489 Most Emacs Lisp file-manipulation functions get errors when used on
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2490 files that are directories. For example, you cannot delete a directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2491 with @code{delete-file}. These special functions exist to create and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2492 delete directories.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2493
102832
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
2494 @findex mkdir
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2495 @defun make-directory dirname &optional parents
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2496 This function creates a directory named @var{dirname}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2497 If @var{parents} is non-@code{nil}, as is always the case in an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2498 interactive call, that means to create the parent directories first,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2499 if they don't already exist.
102832
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
2500
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
2501 @code{mkdir} is an alias for this fuction.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2502 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2503
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2504 @defun delete-directory dirname
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2505 This function deletes the directory named @var{dirname}. The function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2506 @code{delete-file} does not work for files that are directories; you
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2507 must use @code{delete-directory} for them. If the directory contains
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2508 any files, @code{delete-directory} signals an error.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2509
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2510 This function only follows symbolic links at the level of parent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2511 directories.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2512 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2513
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2514 @node Magic File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2515 @section Making Certain File Names ``Magic''
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2516 @cindex magic file names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2517
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2518 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2519 You can implement special handling for certain file names. This is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2520 called making those names @dfn{magic}. The principal use for this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2521 feature is in implementing remote file names (@pxref{Remote Files,,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2522 Remote Files, emacs, The GNU Emacs Manual}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2523
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2524 To define a kind of magic file name, you must supply a regular
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2525 expression to define the class of names (all those that match the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2526 regular expression), plus a handler that implements all the primitive
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2527 Emacs file operations for file names that do match.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2528
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2529 The variable @code{file-name-handler-alist} holds a list of handlers,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2530 together with regular expressions that determine when to apply each
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2531 handler. Each element has this form:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2532
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2533 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2534 (@var{regexp} . @var{handler})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2535 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2536
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2537 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2538 All the Emacs primitives for file access and file name transformation
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2539 check the given file name against @code{file-name-handler-alist}. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2540 the file name matches @var{regexp}, the primitives handle that file by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2541 calling @var{handler}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2542
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2543 The first argument given to @var{handler} is the name of the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2544 primitive, as a symbol; the remaining arguments are the arguments that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2545 were passed to that primitive. (The first of these arguments is most
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2546 often the file name itself.) For example, if you do this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2547
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2548 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2549 (file-exists-p @var{filename})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2550 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2551
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2552 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2553 and @var{filename} has handler @var{handler}, then @var{handler} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2554 called like this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2555
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2556 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2557 (funcall @var{handler} 'file-exists-p @var{filename})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2558 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2559
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2560 When a function takes two or more arguments that must be file names,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2561 it checks each of those names for a handler. For example, if you do
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2562 this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2563
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2564 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2565 (expand-file-name @var{filename} @var{dirname})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2566 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2567
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2568 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2569 then it checks for a handler for @var{filename} and then for a handler
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2570 for @var{dirname}. In either case, the @var{handler} is called like
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2571 this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2572
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2573 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2574 (funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2575 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2576
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2577 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2578 The @var{handler} then needs to figure out whether to handle
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2579 @var{filename} or @var{dirname}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2580
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2581 If the specified file name matches more than one handler, the one
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2582 whose match starts last in the file name gets precedence. This rule
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2583 is chosen so that handlers for jobs such as uncompression are handled
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2584 first, before handlers for jobs such as remote file access.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2585
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2586 Here are the operations that a magic file name handler gets to handle:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2587
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2588 @ifnottex
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2589 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2590 @code{access-file}, @code{add-name-to-file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2591 @code{byte-compiler-base-file-name},@*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2592 @code{copy-file}, @code{delete-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2593 @code{delete-file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2594 @code{diff-latest-backup-file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2595 @code{directory-file-name},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2596 @code{directory-files},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2597 @code{directory-files-and-attributes},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2598 @code{dired-compress-file}, @code{dired-uncache},@*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2599 @code{expand-file-name},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2600 @code{file-accessible-directory-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2601 @code{file-attributes},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2602 @code{file-directory-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2603 @code{file-executable-p}, @code{file-exists-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2604 @code{file-local-copy}, @code{file-remote-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2605 @code{file-modes}, @code{file-name-all-completions},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2606 @code{file-name-as-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2607 @code{file-name-completion},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2608 @code{file-name-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2609 @code{file-name-nondirectory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2610 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2611 @code{file-ownership-preserved-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2612 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2613 @code{file-truename}, @code{file-writable-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2614 @code{find-backup-file-name},
99477
0fd411ceb682 Remove find-file-noselect from the list of magic file name handlers.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 98927
diff changeset
2615 @c Not sure why it was here: @code{find-file-noselect},@*
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2616 @code{get-file-buffer},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2617 @code{insert-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2618 @code{insert-file-contents},@*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2619 @code{load},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2620 @code{make-auto-save-file-name},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2621 @code{make-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2622 @code{make-directory-internal},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2623 @code{make-symbolic-link},@*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2624 @code{process-file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2625 @code{rename-file}, @code{set-file-modes}, @code{set-file-times},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2626 @code{set-visited-file-modtime}, @code{shell-command},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2627 @code{start-file-process},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2628 @code{substitute-in-file-name},@*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2629 @code{unhandled-file-name-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2630 @code{vc-registered},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2631 @code{verify-visited-file-modtime},@*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2632 @code{write-region}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2633 @end ifnottex
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2634 @iftex
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2635 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2636 @flushleft
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2637 @code{access-file}, @code{add-name-to-file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2638 @code{byte-com@discretionary{}{}{}piler-base-file-name},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2639 @code{copy-file}, @code{delete-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2640 @code{delete-file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2641 @code{diff-latest-backup-file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2642 @code{directory-file-name},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2643 @code{directory-files},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2644 @code{directory-files-and-at@discretionary{}{}{}tributes},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2645 @code{dired-compress-file}, @code{dired-uncache},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2646 @code{expand-file-name},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2647 @code{file-accessible-direc@discretionary{}{}{}tory-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2648 @code{file-attributes},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2649 @code{file-direct@discretionary{}{}{}ory-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2650 @code{file-executable-p}, @code{file-exists-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2651 @code{file-local-copy}, @code{file-remote-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2652 @code{file-modes}, @code{file-name-all-completions},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2653 @code{file-name-as-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2654 @code{file-name-completion},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2655 @code{file-name-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2656 @code{file-name-nondirec@discretionary{}{}{}tory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2657 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2658 @code{file-ownership-pre@discretionary{}{}{}served-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2659 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2660 @code{file-truename}, @code{file-writable-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2661 @code{find-backup-file-name},
99477
0fd411ceb682 Remove find-file-noselect from the list of magic file name handlers.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 98927
diff changeset
2662 @c Not sure why it was here: @code{find-file-noselect},
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2663 @code{get-file-buffer},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2664 @code{insert-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2665 @code{insert-file-contents},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2666 @code{load}, @code{make-direc@discretionary{}{}{}tory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2667 @code{make-direc@discretionary{}{}{}tory-internal},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2668 @code{make-symbolic-link},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2669 @code{process-file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2670 @code{rename-file}, @code{set-file-modes},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2671 @code{set-visited-file-modtime}, @code{shell-command},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2672 @code{start-file-process},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2673 @code{substitute-in-file-name},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2674 @code{unhandled-file-name-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2675 @code{vc-regis@discretionary{}{}{}tered},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2676 @code{verify-visited-file-modtime},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2677 @code{write-region}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2678 @end flushleft
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2679 @end iftex
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2680
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2681 Handlers for @code{insert-file-contents} typically need to clear the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2682 buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2683 @var{visit} argument is non-@code{nil}. This also has the effect of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2684 unlocking the buffer if it is locked.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2685
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2686 The handler function must handle all of the above operations, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2687 possibly others to be added in the future. It need not implement all
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2688 these operations itself---when it has nothing special to do for a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2689 certain operation, it can reinvoke the primitive, to handle the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2690 operation ``in the usual way.'' It should always reinvoke the primitive
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2691 for an operation it does not recognize. Here's one way to do this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2692
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2693 @smallexample
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2694 (defun my-file-handler (operation &rest args)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2695 ;; @r{First check for the specific operations}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2696 ;; @r{that we have special handling for.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2697 (cond ((eq operation 'insert-file-contents) @dots{})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2698 ((eq operation 'write-region) @dots{})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2699 @dots{}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2700 ;; @r{Handle any operation we don't know about.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2701 (t (let ((inhibit-file-name-handlers
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2702 (cons 'my-file-handler
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2703 (and (eq inhibit-file-name-operation operation)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2704 inhibit-file-name-handlers)))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2705 (inhibit-file-name-operation operation))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2706 (apply operation args)))))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2707 @end smallexample
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2708
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2709 When a handler function decides to call the ordinary Emacs primitive for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2710 the operation at hand, it needs to prevent the primitive from calling
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2711 the same handler once again, thus leading to an infinite recursion. The
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2712 example above shows how to do this, with the variables
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2713 @code{inhibit-file-name-handlers} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2714 @code{inhibit-file-name-operation}. Be careful to use them exactly as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2715 shown above; the details are crucial for proper behavior in the case of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2716 multiple handlers, and for operations that have two file names that may
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2717 each have handlers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2718
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2719 @kindex safe-magic (@r{property})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2720 Handlers that don't really do anything special for actual access to the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2721 file---such as the ones that implement completion of host names for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2722 remote file names---should have a non-@code{nil} @code{safe-magic}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2723 property. For instance, Emacs normally ``protects'' directory names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2724 it finds in @code{PATH} from becoming magic, if they look like magic
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2725 file names, by prefixing them with @samp{/:}. But if the handler that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2726 would be used for them has a non-@code{nil} @code{safe-magic}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2727 property, the @samp{/:} is not added.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2728
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2729 @kindex operations (@r{property})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2730 A file name handler can have an @code{operations} property to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2731 declare which operations it handles in a nontrivial way. If this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2732 property has a non-@code{nil} value, it should be a list of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2733 operations; then only those operations will call the handler. This
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2734 avoids inefficiency, but its main purpose is for autoloaded handler
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2735 functions, so that they won't be loaded except when they have real
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2736 work to do.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2737
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2738 Simply deferring all operations to the usual primitives does not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2739 work. For instance, if the file name handler applies to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2740 @code{file-exists-p}, then it must handle @code{load} itself, because
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2741 the usual @code{load} code won't work properly in that case. However,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2742 if the handler uses the @code{operations} property to say it doesn't
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2743 handle @code{file-exists-p}, then it need not handle @code{load}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2744 nontrivially.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2745
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2746 @defvar inhibit-file-name-handlers
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2747 This variable holds a list of handlers whose use is presently inhibited
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2748 for a certain operation.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2749 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2750
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2751 @defvar inhibit-file-name-operation
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2752 The operation for which certain handlers are presently inhibited.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2753 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2754
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2755 @defun find-file-name-handler file operation
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2756 This function returns the handler function for file name @var{file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2757 or @code{nil} if there is none. The argument @var{operation} should
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2758 be the operation to be performed on the file---the value you will pass
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2759 to the handler as its first argument when you call it. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2760 @var{operation} equals @code{inhibit-file-name-operation}, or if it is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2761 not found in the @code{operations} property of the handler, this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2762 function returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2763 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2764
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2765 @defun file-local-copy filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2766 This function copies file @var{filename} to an ordinary non-magic file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2767 on the local machine, if it isn't on the local machine already. Magic
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2768 file names should handle the @code{file-local-copy} operation if they
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2769 refer to files on other machines. A magic file name that is used for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2770 other purposes than remote file access should not handle
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2771 @code{file-local-copy}; then this function will treat the file as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2772 local.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2773
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2774 If @var{filename} is local, whether magic or not, this function does
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2775 nothing and returns @code{nil}. Otherwise it returns the file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2776 of the local copy file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2777 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2778
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2779 @defun file-remote-p filename &optional identification connected
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2780 This function tests whether @var{filename} is a remote file. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2781 @var{filename} is local (not remote), the return value is @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2782 If @var{filename} is indeed remote, the return value is a string that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2783 identifies the remote system.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2784
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2785 This identifier string can include a host name and a user name, as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2786 well as characters designating the method used to access the remote
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2787 system. For example, the remote identifier string for the filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2788 @code{/sudo::/some/file} is @code{/sudo:root@@localhost:}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2789
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2790 If @code{file-remote-p} returns the same identifier for two different
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2791 filenames, that means they are stored on the same file system and can
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2792 be accessed locally with respect to each other. This means, for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2793 example, that it is possible to start a remote process accessing both
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2794 files at the same time. Implementors of file handlers need to ensure
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2795 this principle is valid.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2796
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2797 @var{identification} specifies which part of the identifier shall be
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2798 returned as string. @var{identification} can be the symbol
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2799 @code{method}, @code{user} or @code{host}; any other value is handled
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2800 like @code{nil} and means to return the complete identifier string.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2801 In the example above, the remote @code{user} identifier string would
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2802 be @code{root}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2803
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2804 If @var{connected} is non-@code{nil}, this function returns @code{nil}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2805 even if @var{filename} is remote, if Emacs has no network connection
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2806 to its host. This is useful when you want to avoid the delay of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2807 making connections when they don't exist.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2808 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2809
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2810 @defun unhandled-file-name-directory filename
99912
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
2811 This function returns the name of a directory that is not magic. It
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
2812 uses the directory part of @var{filename} if that is not magic. For a
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
2813 magic file name, it invokes the file name handler, which therefore
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
2814 decides what value to return. If @var{filename} is not accessible
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
2815 from a local process, then the file name handler should indicate it by
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
2816 returning @code{nil}.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2817
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2818 This is useful for running a subprocess; every subprocess must have a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2819 non-magic directory to serve as its current directory, and this function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2820 is a good way to come up with one.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2821 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2822
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2823 @node Format Conversion
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2824 @section File Format Conversion
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2825
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2826 @cindex file format conversion
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2827 @cindex encoding file formats
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2828 @cindex decoding file formats
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2829 @cindex text properties in files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2830 @cindex saving text properties
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2831 Emacs performs several steps to convert the data in a buffer (text,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2832 text properties, and possibly other information) to and from a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2833 representation suitable for storing into a file. This section describes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2834 the fundamental functions that perform this @dfn{format conversion},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2835 namely @code{insert-file-contents} for reading a file into a buffer,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2836 and @code{write-region} for writing a buffer into a file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2837
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2838 @menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2839 * Overview: Format Conversion Overview. @code{insert-file-contents} and @code{write-region}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2840 * Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2841 * Piecemeal: Format Conversion Piecemeal. Specifying non-paired conversion.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2842 @end menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2843
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2844 @node Format Conversion Overview
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2845 @subsection Overview
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2846 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2847 The function @code{insert-file-contents}:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2848
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2849 @itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2850 @item initially, inserts bytes from the file into the buffer;
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2851 @item decodes bytes to characters as appropriate;
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2852 @item processes formats as defined by entries in @code{format-alist}; and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2853 @item calls functions in @code{after-insert-file-functions}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2854 @end itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2855
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2856 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2857 The function @code{write-region}:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2858
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2859 @itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2860 @item initially, calls functions in @code{write-region-annotate-functions};
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2861 @item processes formats as defined by entries in @code{format-alist};
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2862 @item encodes characters to bytes as appropriate; and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2863 @item modifies the file with the bytes.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2864 @end itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2865
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2866 This shows the symmetry of the lowest-level operations; reading and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2867 writing handle things in opposite order. The rest of this section
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2868 describes the two facilities surrounding the three variables named
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2869 above, as well as some related functions. @ref{Coding Systems}, for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2870 details on character encoding and decoding.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2871
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2872 @node Format Conversion Round-Trip
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2873 @subsection Round-Trip Specification
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2874
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2875 The most general of the two facilities is controlled by the variable
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2876 @code{format-alist}, a list of @dfn{file format} specifications, which
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2877 describe textual representations used in files for the data in an Emacs
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2878 buffer. The descriptions for reading and writing are paired, which is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2879 why we call this ``round-trip'' specification
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2880 (@pxref{Format Conversion Piecemeal}, for non-paired specification).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2881
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2882 @defvar format-alist
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2883 This list contains one format definition for each defined file format.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2884 Each format definition is a list of this form:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2885
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2886 @example
99733
15f3f8c7992a (Format Conversion Round-Trip): Mention `preserve' element of `format-alist'.
Glenn Morris <rgm@gnu.org>
parents: 99526
diff changeset
2887 (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn} @var{preserve})
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2888 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2889 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2890
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2891 @cindex format definition
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2892 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2893 Here is what the elements in a format definition mean:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2894
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2895 @table @var
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2896 @item name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2897 The name of this format.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2898
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2899 @item doc-string
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2900 A documentation string for the format.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2901
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2902 @item regexp
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2903 A regular expression which is used to recognize files represented in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2904 this format.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2905
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2906 @item from-fn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2907 A shell command or function to decode data in this format (to convert
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2908 file data into the usual Emacs data representation).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2909
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2910 A shell command is represented as a string; Emacs runs the command as a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2911 filter to perform the conversion.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2912
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2913 If @var{from-fn} is a function, it is called with two arguments, @var{begin}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2914 and @var{end}, which specify the part of the buffer it should convert.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2915 It should convert the text by editing it in place. Since this can
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2916 change the length of the text, @var{from-fn} should return the modified
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2917 end position.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2918
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2919 One responsibility of @var{from-fn} is to make sure that the beginning
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2920 of the file no longer matches @var{regexp}. Otherwise it is likely to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2921 get called again.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2922
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2923 @item to-fn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2924 A shell command or function to encode data in this format---that is, to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2925 convert the usual Emacs data representation into this format.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2926
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2927 If @var{to-fn} is a string, it is a shell command; Emacs runs the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2928 command as a filter to perform the conversion.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2929
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2930 If @var{to-fn} is a function, it is called with three arguments:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2931 @var{begin} and @var{end}, which specify the part of the buffer it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2932 should convert, and @var{buffer}, which specifies which buffer. There
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2933 are two ways it can do the conversion:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2934
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2935 @itemize @bullet
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2936 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2937 By editing the buffer in place. In this case, @var{to-fn} should
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2938 return the end-position of the range of text, as modified.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2939
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2940 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2941 By returning a list of annotations. This is a list of elements of the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2942 form @code{(@var{position} . @var{string})}, where @var{position} is an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2943 integer specifying the relative position in the text to be written, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2944 @var{string} is the annotation to add there. The list must be sorted in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2945 order of position when @var{to-fn} returns it.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2946
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2947 When @code{write-region} actually writes the text from the buffer to the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2948 file, it intermixes the specified annotations at the corresponding
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2949 positions. All this takes place without modifying the buffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2950 @end itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2951
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2952 @item modify
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2953 A flag, @code{t} if the encoding function modifies the buffer, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2954 @code{nil} if it works by returning a list of annotations.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2955
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2956 @item mode-fn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2957 A minor-mode function to call after visiting a file converted from this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2958 format. The function is called with one argument, the integer 1;
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2959 that tells a minor-mode function to enable the mode.
99733
15f3f8c7992a (Format Conversion Round-Trip): Mention `preserve' element of `format-alist'.
Glenn Morris <rgm@gnu.org>
parents: 99526
diff changeset
2960
15f3f8c7992a (Format Conversion Round-Trip): Mention `preserve' element of `format-alist'.
Glenn Morris <rgm@gnu.org>
parents: 99526
diff changeset
2961 @item preserve
15f3f8c7992a (Format Conversion Round-Trip): Mention `preserve' element of `format-alist'.
Glenn Morris <rgm@gnu.org>
parents: 99526
diff changeset
2962 A flag, @code{t} if @code{format-write-file} should not remove this format
15f3f8c7992a (Format Conversion Round-Trip): Mention `preserve' element of `format-alist'.
Glenn Morris <rgm@gnu.org>
parents: 99526
diff changeset
2963 from @code{buffer-file-format}.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2964 @end table
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2965
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2966 The function @code{insert-file-contents} automatically recognizes file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2967 formats when it reads the specified file. It checks the text of the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2968 beginning of the file against the regular expressions of the format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2969 definitions, and if it finds a match, it calls the decoding function for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2970 that format. Then it checks all the known formats over again.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2971 It keeps checking them until none of them is applicable.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2972
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2973 Visiting a file, with @code{find-file-noselect} or the commands that use
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2974 it, performs conversion likewise (because it calls
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2975 @code{insert-file-contents}); it also calls the mode function for each
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2976 format that it decodes. It stores a list of the format names in the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2977 buffer-local variable @code{buffer-file-format}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2978
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2979 @defvar buffer-file-format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2980 This variable states the format of the visited file. More precisely,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2981 this is a list of the file format names that were decoded in the course
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2982 of visiting the current buffer's file. It is always buffer-local in all
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2983 buffers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2984 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2985
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2986 When @code{write-region} writes data into a file, it first calls the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2987 encoding functions for the formats listed in @code{buffer-file-format},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2988 in the order of appearance in the list.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2989
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2990 @deffn Command format-write-file file format &optional confirm
100115
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
2991 This command writes the current buffer contents into the file @var{file}
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
2992 in a format based on @var{format}, which is a list of format names. It
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
2993 constructs the actual format starting from @var{format}, then appending
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
2994 any elements from the value of @code{buffer-file-format} with a non-nil
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
2995 @var{preserve} flag (see above), if they are not already present in
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
2996 @var{format}. It then updates @code{buffer-file-format} with this
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
2997 format, making it the default for future saves. Except for the
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
2998 @var{format} argument, this command is similar to @code{write-file}. In
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
2999 particular, @var{confirm} has the same meaning and interactive treatment
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
3000 as the corresponding argument to @code{write-file}. @xref{Definition of
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
3001 write-file}.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3002 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3003
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3004 @deffn Command format-find-file file format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3005 This command finds the file @var{file}, converting it according to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3006 format @var{format}. It also makes @var{format} the default if the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3007 buffer is saved later.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3008
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3009 The argument @var{format} is a list of format names. If @var{format} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3010 @code{nil}, no conversion takes place. Interactively, typing just
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3011 @key{RET} for @var{format} specifies @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3012 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3013
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3014 @deffn Command format-insert-file file format &optional beg end
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3015 This command inserts the contents of file @var{file}, converting it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3016 according to format @var{format}. If @var{beg} and @var{end} are
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3017 non-@code{nil}, they specify which part of the file to read, as in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3018 @code{insert-file-contents} (@pxref{Reading from Files}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3019
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3020 The return value is like what @code{insert-file-contents} returns: a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3021 list of the absolute file name and the length of the data inserted
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3022 (after conversion).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3023
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3024 The argument @var{format} is a list of format names. If @var{format} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3025 @code{nil}, no conversion takes place. Interactively, typing just
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3026 @key{RET} for @var{format} specifies @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3027 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3028
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3029 @defvar buffer-auto-save-file-format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3030 This variable specifies the format to use for auto-saving. Its value is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3031 a list of format names, just like the value of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3032 @code{buffer-file-format}; however, it is used instead of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3033 @code{buffer-file-format} for writing auto-save files. If the value
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3034 is @code{t}, the default, auto-saving uses the same format as a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3035 regular save in the same buffer. This variable is always buffer-local
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3036 in all buffers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3037 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3038
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3039 @node Format Conversion Piecemeal
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3040 @subsection Piecemeal Specification
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3041
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3042 In contrast to the round-trip specification described in the previous
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3043 subsection (@pxref{Format Conversion Round-Trip}), you can use the variables
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3044 @code{after-insert-file-functions} and @code{write-region-annotate-functions}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3045 to separately control the respective reading and writing conversions.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3046
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3047 Conversion starts with one representation and produces another
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3048 representation. When there is only one conversion to do, there is no
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3049 conflict about what to start with. However, when there are multiple
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3050 conversions involved, conflict may arise when two conversions need to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3051 start with the same data.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3052
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3053 This situation is best understood in the context of converting text
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3054 properties during @code{write-region}. For example, the character at
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3055 position 42 in a buffer is @samp{X} with a text property @code{foo}. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3056 the conversion for @code{foo} is done by inserting into the buffer, say,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3057 @samp{FOO:}, then that changes the character at position 42 from
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3058 @samp{X} to @samp{F}. The next conversion will start with the wrong
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3059 data straight away.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3060
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3061 To avoid conflict, cooperative conversions do not modify the buffer,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3062 but instead specify @dfn{annotations}, a list of elements of the form
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3063 @code{(@var{position} . @var{string})}, sorted in order of increasing
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3064 @var{position}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3065
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3066 If there is more than one conversion, @code{write-region} merges their
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3067 annotations destructively into one sorted list. Later, when the text
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3068 from the buffer is actually written to the file, it intermixes the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3069 specified annotations at the corresponding positions. All this takes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3070 place without modifying the buffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3071
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3072 @c ??? What about ``overriding'' conversions like those allowed
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3073 @c ??? for `write-region-annotate-functions', below? --ttn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3074
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3075 In contrast, when reading, the annotations intermixed with the text
101344
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3076 are handled immediately. @code{insert-file-contents} sets point to
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3077 the beginning of some text to be converted, then calls the conversion
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3078 functions with the length of that text. These functions should always
101344
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3079 return with point at the beginning of the inserted text. This
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3080 approach makes sense for reading because annotations removed by the
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3081 first converter can't be mistakenly processed by a later converter.
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3082 Each conversion function should scan for the annotations it
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3083 recognizes, remove the annotation, modify the buffer text (to set a
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3084 text property, for example), and return the updated length of the
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3085 text, as it stands after those changes. The value returned by one
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3086 function becomes the argument to the next function.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3087
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3088 @defvar write-region-annotate-functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3089 A list of functions for @code{write-region} to call. Each function in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3090 the list is called with two arguments: the start and end of the region
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3091 to be written. These functions should not alter the contents of the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3092 buffer. Instead, they should return annotations.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3093
101344
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3094 As a special case, a function may return with a different buffer
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3095 current. Emacs takes this to mean that the current buffer contains
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3096 altered text to be output. It therefore changes the @var{start} and
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3097 @var{end} arguments of the @code{write-region} call, giving them the
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3098 values of @code{point-min} and @code{point-max} in the new buffer,
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3099 respectively. It also discards all previous annotations, because they
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3100 should have been dealt with by this function.
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3101 @end defvar
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3102
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3103 @defvar write-region-post-annotation-function
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3104 The value of this variable, if non-@code{nil}, should be a function.
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3105 This function is called, with no arguments, after @code{write-region}
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3106 has completed.
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3107
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3108 If any function in @code{write-region-annotate-functions} returns with
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3109 a different buffer current, Emacs calls
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3110 @code{write-region-post-annotation-function} more than once. Emacs
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3111 calls it with the last buffer that was current, and again with the
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3112 buffer before that, and so on back to the original buffer.
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3113
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3114 Thus, a function in @code{write-region-annotate-functions} can create
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3115 a buffer, give this variable the local value of @code{kill-buffer} in
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3116 that buffer, set up the buffer with altered text, and make the buffer
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3117 current. The buffer will be killed after @code{write-region} is done.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3118 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3119
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3120 @defvar after-insert-file-functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3121 Each function in this list is called by @code{insert-file-contents}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3122 with one argument, the number of characters inserted, and with point
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3123 at the beginning of the inserted text. Each function should leave
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3124 point unchanged, and return the new character count describing the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3125 inserted text as modified by the function.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3126 @c ??? The docstring mentions a handler from `file-name-handler-alist'
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3127 @c "intercepting" `insert-file-contents'. Hmmm. --ttn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3128 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3129
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3130 We invite users to write Lisp programs to store and retrieve text
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3131 properties in files, using these hooks, and thus to experiment with
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3132 various data formats and find good ones. Eventually we hope users
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3133 will produce good, general extensions we can install in Emacs.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3134
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3135 We suggest not trying to handle arbitrary Lisp objects as text property
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3136 names or values---because a program that general is probably difficult
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3137 to write, and slow. Instead, choose a set of possible data types that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3138 are reasonably flexible, and not too hard to encode.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3139
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3140 @ignore
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3141 arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3142 @end ignore