Mercurial > emacs
annotate lispref/files.texi @ 27114:4efa5e54e9a9
(Qunspecified_fg, Qunspecified_bg): Remove.
(syms_of_xfaces): Remove their staticpro's.
(tty_color_name): Return Lisp strings for unspecified fore- and
back-ground colors.
(Finternal_set_lisp_face_attribute): Remove the special treatment
for Qunspecified_{f,b}g.
(realize_default_face): Replace Qunspecified_{f,b}g with a Lisp
string.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Mon, 03 Jan 2000 16:52:52 +0000 |
parents | 2d8554ed8748 |
children | f6b52258db6a |
rev | line source |
---|---|
6555 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. |
6555 | 4 @c See the file elisp.texi for copying conditions. |
5 @setfilename ../info/files | |
6 @node Files, Backups and Auto-Saving, Documentation, Top | |
7 @comment node-name, next, previous, up | |
8 @chapter Files | |
9 | |
10 In Emacs, you can find, create, view, save, and otherwise work with | |
11 files and file directories. This chapter describes most of the | |
12 file-related functions of Emacs Lisp, but a few others are described in | |
13 @ref{Buffers}, and those related to backups and auto-saving are | |
14 described in @ref{Backups and Auto-Saving}. | |
15 | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
16 Many of the file functions take one or more arguments that are file |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
17 names. A file name is actually a string. Most of these functions |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
18 expand file name arguments by calling @code{expand-file-name}, so that |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
19 @file{~} is handled correctly, as are relative file names (including |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
20 @samp{../}). These functions don't recognize environment variable |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
21 substitutions such as @samp{$HOME}. @xref{File Name Expansion}. |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
22 |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
23 When file I/O functions signal Lisp errors, they usually use the |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
24 condition @code{file-error} (@pxref{Handling Errors}). The error |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
25 message is in most cases obtained from the operating system, according |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
26 to locale @code{system-message-locale}, and decoded using coding system |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
27 @code{locale-coding-system} (@pxref{Locales}). |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
28 |
6555 | 29 @menu |
30 * Visiting Files:: Reading files into Emacs buffers for editing. | |
31 * Saving Buffers:: Writing changed buffers back into files. | |
32 * Reading from Files:: Reading files into buffers without visiting. | |
33 * Writing to Files:: Writing new files from parts of buffers. | |
34 * File Locks:: Locking and unlocking files, to prevent | |
35 simultaneous editing by two people. | |
36 * Information about Files:: Testing existence, accessibility, size of files. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
37 * Changing Files:: Renaming files, changing protection, etc. |
6555 | 38 * File Names:: Decomposing and expanding file names. |
39 * Contents of Directories:: Getting a list of the files in a directory. | |
40 * Create/Delete Dirs:: Creating and Deleting Directories. | |
41 * Magic File Names:: Defining "magic" special handling | |
42 for certain file names. | |
12067 | 43 * Format Conversion:: Conversion to and from various file formats. |
6555 | 44 @end menu |
45 | |
46 @node Visiting Files | |
47 @section Visiting Files | |
48 @cindex finding files | |
49 @cindex visiting files | |
50 | |
51 Visiting a file means reading a file into a buffer. Once this is | |
52 done, we say that the buffer is @dfn{visiting} that file, and call the | |
53 file ``the visited file'' of the buffer. | |
54 | |
55 A file and a buffer are two different things. A file is information | |
56 recorded permanently in the computer (unless you delete it). A buffer, | |
57 on the other hand, is information inside of Emacs that will vanish at | |
58 the end of the editing session (or when you kill the buffer). Usually, | |
59 a buffer contains information that you have copied from a file; then we | |
60 say the buffer is visiting that file. The copy in the buffer is what | |
61 you modify with editing commands. Such changes to the buffer do not | |
62 change the file; therefore, to make the changes permanent, you must | |
63 @dfn{save} the buffer, which means copying the altered buffer contents | |
64 back into the file. | |
65 | |
66 In spite of the distinction between files and buffers, people often | |
67 refer to a file when they mean a buffer and vice-versa. Indeed, we say, | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
68 ``I am editing a file,'' rather than, ``I am editing a buffer that I |
6555 | 69 will soon save as a file of the same name.'' Humans do not usually need |
70 to make the distinction explicit. When dealing with a computer program, | |
71 however, it is good to keep the distinction in mind. | |
72 | |
73 @menu | |
74 * Visiting Functions:: The usual interface functions for visiting. | |
75 * Subroutines of Visiting:: Lower-level subroutines that they use. | |
76 @end menu | |
77 | |
78 @node Visiting Functions | |
79 @subsection Functions for Visiting Files | |
80 | |
81 This section describes the functions normally used to visit files. | |
82 For historical reasons, these functions have names starting with | |
83 @samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for | |
84 functions and variables that access the visited file name of a buffer or | |
85 that find an existing buffer by its visited file name. | |
86 | |
12098 | 87 In a Lisp program, if you want to look at the contents of a file but |
88 not alter it, the fastest way is to use @code{insert-file-contents} in a | |
89 temporary buffer. Visiting the file is not necessary and takes longer. | |
90 @xref{Reading from Files}. | |
91 | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
92 @deffn Command find-file filename &optional wildcards |
6555 | 93 This command selects a buffer visiting the file @var{filename}, |
94 using an existing buffer if there is one, and otherwise creating a | |
95 new buffer and reading the file into it. It also returns that buffer. | |
96 | |
97 The body of the @code{find-file} function is very simple and looks | |
98 like this: | |
99 | |
100 @example | |
101 (switch-to-buffer (find-file-noselect filename)) | |
102 @end example | |
103 | |
104 @noindent | |
105 (See @code{switch-to-buffer} in @ref{Displaying Buffers}.) | |
106 | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
107 If @var{wildcards} is non-@code{nil}, which is always true in an |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
108 interactive call, then @code{find-file} expands wildcard characters in |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
109 @var{filename} and visits all the matching files. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
110 |
6555 | 111 When @code{find-file} is called interactively, it prompts for |
112 @var{filename} in the minibuffer. | |
113 @end deffn | |
114 | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
115 @defun find-file-noselect filename &optional nowarn rawfile wildcards |
6555 | 116 This function is the guts of all the file-visiting functions. It finds |
117 or creates a buffer visiting the file @var{filename}, and returns it. | |
118 It uses an existing buffer if there is one, and otherwise creates a new | |
119 buffer and reads the file into it. You may make the buffer current or | |
120 display it in a window if you wish, but this function does not do so. | |
121 | |
24952 | 122 If @var{wildcards} is non-@code{nil}, |
123 then @code{find-file-noselect} expands wildcard | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
124 characters in @var{filename} and visits all the matching files. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
125 |
6555 | 126 When @code{find-file-noselect} uses an existing buffer, it first |
127 verifies that the file has not changed since it was last visited or | |
128 saved in that buffer. If the file has changed, then this function asks | |
129 the user whether to reread the changed file. If the user says | |
130 @samp{yes}, any changes previously made in the buffer are lost. | |
131 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
132 This function displays warning or advisory messages in various peculiar |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
133 cases, unless the optional argument @var{nowarn} is non-@code{nil}. For |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
134 example, if it needs to create a buffer, and there is no file named |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
135 @var{filename}, it displays the message @samp{(New file)} in the echo |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
136 area, and leaves the buffer empty. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
137 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
138 The @code{find-file-noselect} function normally calls |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
139 @code{after-find-file} after reading the file (@pxref{Subroutines of |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
140 Visiting}). That function sets the buffer major mode, parses local |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
141 variables, warns the user if there exists an auto-save file more recent |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
142 than the file just visited, and finishes by running the functions in |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
143 @code{find-file-hooks}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
144 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
145 If the optional argument @var{rawfile} is non-@code{nil}, then |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
146 @code{after-find-file} is not called, and the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
147 @code{find-file-not-found-hooks} are not run in case of failure. What's |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
148 more, a non-@code{nil} @var{rawfile} value suppresses coding system |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
149 conversion (@pxref{Coding Systems}) and format conversion (@pxref{Format |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
150 Conversion}). |
6555 | 151 |
152 The @code{find-file-noselect} function returns the buffer that is | |
153 visiting the file @var{filename}. | |
154 | |
155 @example | |
156 @group | |
157 (find-file-noselect "/etc/fstab") | |
158 @result{} #<buffer fstab> | |
159 @end group | |
160 @end example | |
161 @end defun | |
162 | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
163 @deffn Command find-file-other-window filename &optional wildcards |
6555 | 164 This command selects a buffer visiting the file @var{filename}, but |
165 does so in a window other than the selected window. It may use another | |
166 existing window or split a window; see @ref{Displaying Buffers}. | |
167 | |
168 When this command is called interactively, it prompts for | |
169 @var{filename}. | |
170 @end deffn | |
171 | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
172 @deffn Command find-file-read-only filename &optional wildcards |
6555 | 173 This command selects a buffer visiting the file @var{filename}, like |
174 @code{find-file}, but it marks the buffer as read-only. @xref{Read Only | |
175 Buffers}, for related functions and variables. | |
176 | |
177 When this command is called interactively, it prompts for | |
178 @var{filename}. | |
179 @end deffn | |
180 | |
181 @deffn Command view-file filename | |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
182 This command visits @var{filename} using View mode, returning to the |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
183 previous buffer when you exit View mode. View mode is a minor mode that |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
184 provides commands to skim rapidly through the file, but does not let you |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
185 modify the text. Entering View mode runs the normal hook |
12098 | 186 @code{view-mode-hook}. @xref{Hooks}. |
6555 | 187 |
188 When @code{view-file} is called interactively, it prompts for | |
189 @var{filename}. | |
190 @end deffn | |
191 | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
192 @tindex find-file-wildcards |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
193 @defvar find-file-wildcards |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
194 If this variable is non-@code{nil}, then the various @code{find-file} |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
195 commands check for wildcard characters and visit all the files that |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
196 match them. If this is @code{nil}, then wildcard characters are |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
197 not treated specially. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
198 @end defvar |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
199 |
6555 | 200 @defvar find-file-hooks |
201 The value of this variable is a list of functions to be called after a | |
202 file is visited. The file's local-variables specification (if any) will | |
203 have been processed before the hooks are run. The buffer visiting the | |
204 file is current when the hook functions are run. | |
205 | |
206 This variable works just like a normal hook, but we think that renaming | |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
207 it would not be advisable. @xref{Hooks}. |
6555 | 208 @end defvar |
209 | |
210 @defvar find-file-not-found-hooks | |
211 The value of this variable is a list of functions to be called when | |
212 @code{find-file} or @code{find-file-noselect} is passed a nonexistent | |
213 file name. @code{find-file-noselect} calls these functions as soon as | |
214 it detects a nonexistent file. It calls them in the order of the list, | |
215 until one of them returns non-@code{nil}. @code{buffer-file-name} is | |
216 already set up. | |
217 | |
218 This is not a normal hook because the values of the functions are | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
219 used, and in many cases only some of the functions are called. |
6555 | 220 @end defvar |
221 | |
222 @node Subroutines of Visiting | |
223 @comment node-name, next, previous, up | |
224 @subsection Subroutines of Visiting | |
225 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
226 The @code{find-file-noselect} function uses two important subroutines |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
227 which are sometimes useful in user Lisp code: @code{create-file-buffer} |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
228 and @code{after-find-file}. This section explains how to use them. |
6555 | 229 |
230 @defun create-file-buffer filename | |
231 This function creates a suitably named buffer for visiting | |
232 @var{filename}, and returns it. It uses @var{filename} (sans directory) | |
233 as the name if that name is free; otherwise, it appends a string such as | |
234 @samp{<2>} to get an unused name. See also @ref{Creating Buffers}. | |
235 | |
236 @strong{Please note:} @code{create-file-buffer} does @emph{not} | |
237 associate the new buffer with a file and does not select the buffer. | |
12098 | 238 It also does not use the default major mode. |
6555 | 239 |
240 @example | |
241 @group | |
242 (create-file-buffer "foo") | |
243 @result{} #<buffer foo> | |
244 @end group | |
245 @group | |
246 (create-file-buffer "foo") | |
247 @result{} #<buffer foo<2>> | |
248 @end group | |
249 @group | |
250 (create-file-buffer "foo") | |
251 @result{} #<buffer foo<3>> | |
252 @end group | |
253 @end example | |
254 | |
255 This function is used by @code{find-file-noselect}. | |
256 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}). | |
257 @end defun | |
258 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
259 @defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes |
6555 | 260 This function sets the buffer major mode, and parses local variables |
261 (@pxref{Auto Major Mode}). It is called by @code{find-file-noselect} | |
262 and by the default revert function (@pxref{Reverting}). | |
263 | |
264 @cindex new file message | |
265 @cindex file open error | |
266 If reading the file got an error because the file does not exist, but | |
267 its directory does exist, the caller should pass a non-@code{nil} value | |
268 for @var{error}. In that case, @code{after-find-file} issues a warning: | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
269 @samp{(New file)}. For more serious errors, the caller should usually not |
6555 | 270 call @code{after-find-file}. |
271 | |
272 If @var{warn} is non-@code{nil}, then this function issues a warning | |
273 if an auto-save file exists and is more recent than the visited file. | |
274 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
275 If @var{noauto} is non-@code{nil}, that says not to enable or disable |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
276 Auto-Save mode. The mode remains enabled if it was enabled before. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
277 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
278 If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
279 means this call was from @code{revert-buffer}. This has no direct |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
280 effect, but some mode functions and hook functions check the value |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
281 of this variable. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
282 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
283 If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
284 major mode, don't process local variables specifications in the file, |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
285 and don't run @code{find-file-hooks}. This feature is used by |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
286 @code{revert-buffer} in some cases. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
287 |
6555 | 288 The last thing @code{after-find-file} does is call all the functions |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
289 in the list @code{find-file-hooks}. |
6555 | 290 @end defun |
291 | |
292 @node Saving Buffers | |
293 @section Saving Buffers | |
294 | |
295 When you edit a file in Emacs, you are actually working on a buffer | |
296 that is visiting that file---that is, the contents of the file are | |
297 copied into the buffer and the copy is what you edit. Changes to the | |
298 buffer do not change the file until you @dfn{save} the buffer, which | |
299 means copying the contents of the buffer into the file. | |
300 | |
301 @deffn Command save-buffer &optional backup-option | |
302 This function saves the contents of the current buffer in its visited | |
303 file if the buffer has been modified since it was last visited or saved. | |
304 Otherwise it does nothing. | |
305 | |
306 @code{save-buffer} is responsible for making backup files. Normally, | |
307 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
308 file only if this is the first save since visiting the file. Other |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
309 values for @var{backup-option} request the making of backup files in |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
310 other circumstances: |
6555 | 311 |
312 @itemize @bullet | |
313 @item | |
314 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the | |
315 @code{save-buffer} function marks this version of the file to be | |
316 backed up when the buffer is next saved. | |
317 | |
318 @item | |
319 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the | |
320 @code{save-buffer} function unconditionally backs up the previous | |
321 version of the file before saving it. | |
322 @end itemize | |
323 @end deffn | |
324 | |
26770
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
325 @deffn Command save-some-buffers &optional save-silently-p pred |
6555 | 326 This command saves some modified file-visiting buffers. Normally it |
327 asks the user about each buffer. But if @var{save-silently-p} is | |
328 non-@code{nil}, it saves all the file-visiting buffers without querying | |
329 the user. | |
330 | |
26770
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
331 The optional @var{pred} argument controls which buffers to ask about. |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
332 If it is @code{nil}, that means to ask only about file-visiting buffers. |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
333 If it is @code{t}, that means also offer to save certain other non-file |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
334 buffers---those that have a non-@code{nil} buffer-local value of |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
335 @code{buffer-offer-save}. (A user who says @samp{yes} to saving a |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
336 non-file buffer is asked to specify the file name to use.) The |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
337 @code{save-buffers-kill-emacs} function passes the value @code{t} for |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
338 @var{pred}. |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
339 |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
340 If @var{pred} is neither @code{t} nor @code{nil}, then it should be |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
341 a function of no arguments. It will be called in each buffer to decide |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
342 whether to offer to save that buffer. If it returns a non-@code{nil} |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
343 value in a certain buffer, that means do offer to save that buffer. |
6555 | 344 @end deffn |
345 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
346 @deffn Command write-file filename &optional confirm |
6555 | 347 This function writes the current buffer into file @var{filename}, makes |
348 the buffer visit that file, and marks it not modified. Then it renames | |
349 the buffer based on @var{filename}, appending a string like @samp{<2>} | |
350 if necessary to make a unique buffer name. It does most of this work by | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
351 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
352 @code{save-buffer}. |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
353 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
354 If @var{confirm} is non-@code{nil}, that means to ask for confirmation |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
355 before overwriting an existing file. |
6555 | 356 @end deffn |
357 | |
15913
f415fdc67ad3
Add xrefs from Saving Buffers to Format Conversion and Saving
Richard M. Stallman <rms@gnu.org>
parents:
15765
diff
changeset
|
358 Saving a buffer runs several hooks. It also performs format |
f415fdc67ad3
Add xrefs from Saving Buffers to Format Conversion and Saving
Richard M. Stallman <rms@gnu.org>
parents:
15765
diff
changeset
|
359 conversion (@pxref{Format Conversion}), and may save text properties in |
f415fdc67ad3
Add xrefs from Saving Buffers to Format Conversion and Saving
Richard M. Stallman <rms@gnu.org>
parents:
15765
diff
changeset
|
360 ``annotations'' (@pxref{Saving Properties}). |
f415fdc67ad3
Add xrefs from Saving Buffers to Format Conversion and Saving
Richard M. Stallman <rms@gnu.org>
parents:
15765
diff
changeset
|
361 |
6555 | 362 @defvar write-file-hooks |
363 The value of this variable is a list of functions to be called before | |
364 writing out a buffer to its visited file. If one of them returns | |
365 non-@code{nil}, the file is considered already written and the rest of | |
366 the functions are not called, nor is the usual code for writing the file | |
367 executed. | |
368 | |
369 If a function in @code{write-file-hooks} returns non-@code{nil}, it | |
370 is responsible for making a backup file (if that is appropriate). | |
371 To do so, execute the following code: | |
372 | |
373 @example | |
374 (or buffer-backed-up (backup-buffer)) | |
375 @end example | |
376 | |
377 You might wish to save the file modes value returned by | |
378 @code{backup-buffer} and use that to set the mode bits of the file that | |
379 you write. This is what @code{save-buffer} normally does. | |
380 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
381 The hook functions in @code{write-file-hooks} are also responsible for |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
382 encoding the data (if desired): they must choose a suitable coding |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
383 system (@pxref{Lisp and Coding Systems}), perform the encoding |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
384 (@pxref{Explicit Encoding}), and set @code{last-coding-system-used} to |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
385 the coding system that was used (@pxref{Encoding and I/O}). |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
386 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
387 Do not make this variable buffer-local. To set up buffer-specific hook |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
388 functions, use @code{write-contents-hooks} instead. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
389 |
6555 | 390 Even though this is not a normal hook, you can use @code{add-hook} and |
391 @code{remove-hook} to manipulate the list. @xref{Hooks}. | |
392 @end defvar | |
393 | |
394 @c Emacs 19 feature | |
395 @defvar local-write-file-hooks | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
396 This works just like @code{write-file-hooks}, but it is intended to be |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
397 made buffer-local in particular buffers, and used for hooks that pertain |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
398 to the file name or the way the buffer contents were obtained. |
6555 | 399 |
400 The variable is marked as a permanent local, so that changing the major | |
401 mode does not alter a buffer-local value. This is convenient for | |
402 packages that read ``file'' contents in special ways, and set up hooks | |
403 to save the data in a corresponding way. | |
404 @end defvar | |
405 | |
406 @c Emacs 19 feature | |
407 @defvar write-contents-hooks | |
408 This works just like @code{write-file-hooks}, but it is intended for | |
409 hooks that pertain to the contents of the file, as opposed to hooks that | |
8364 | 410 pertain to where the file came from. Such hooks are usually set up by |
14152
9c9debb5950f
Clarify write-contents-hooks.
Richard M. Stallman <rms@gnu.org>
parents:
12674
diff
changeset
|
411 major modes, as buffer-local bindings for this variable. |
9c9debb5950f
Clarify write-contents-hooks.
Richard M. Stallman <rms@gnu.org>
parents:
12674
diff
changeset
|
412 |
9c9debb5950f
Clarify write-contents-hooks.
Richard M. Stallman <rms@gnu.org>
parents:
12674
diff
changeset
|
413 This variable automatically becomes buffer-local whenever it is set; |
9c9debb5950f
Clarify write-contents-hooks.
Richard M. Stallman <rms@gnu.org>
parents:
12674
diff
changeset
|
414 switching to a new major mode always resets this variable. When you use |
9c9debb5950f
Clarify write-contents-hooks.
Richard M. Stallman <rms@gnu.org>
parents:
12674
diff
changeset
|
415 @code{add-hooks} to add an element to this hook, you should @emph{not} |
9c9debb5950f
Clarify write-contents-hooks.
Richard M. Stallman <rms@gnu.org>
parents:
12674
diff
changeset
|
416 specify a non-@code{nil} @var{local} argument, since this variable is |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
417 used @emph{only} buffer-locally. |
6555 | 418 @end defvar |
419 | |
420 @c Emacs 19 feature | |
421 @defvar after-save-hook | |
422 This normal hook runs after a buffer has been saved in its visited file. | |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
423 One use of this hook is in Fast Lock mode; it uses this hook to save the |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
424 highlighting information in a cache file. |
6555 | 425 @end defvar |
426 | |
427 @defvar file-precious-flag | |
428 If this variable is non-@code{nil}, then @code{save-buffer} protects | |
429 against I/O errors while saving by writing the new file to a temporary | |
430 name instead of the name it is supposed to have, and then renaming it to | |
431 the intended name after it is clear there are no errors. This procedure | |
432 prevents problems such as a lack of disk space from resulting in an | |
433 invalid file. | |
434 | |
12226 | 435 As a side effect, backups are necessarily made by copying. @xref{Rename |
436 or Copy}. Yet, at the same time, saving a precious file always breaks | |
437 all hard links between the file you save and other file names. | |
6555 | 438 |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
439 Some modes give this variable a non-@code{nil} buffer-local value |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
440 in particular buffers. |
6555 | 441 @end defvar |
442 | |
443 @defopt require-final-newline | |
444 This variable determines whether files may be written out that do | |
445 @emph{not} end with a newline. If the value of the variable is | |
446 @code{t}, then @code{save-buffer} silently adds a newline at the end of | |
447 the file whenever the buffer being saved does not already end in one. | |
448 If the value of the variable is non-@code{nil}, but not @code{t}, then | |
449 @code{save-buffer} asks the user whether to add a newline each time the | |
450 case arises. | |
451 | |
452 If the value of the variable is @code{nil}, then @code{save-buffer} | |
453 doesn't add newlines at all. @code{nil} is the default value, but a few | |
454 major modes set it to @code{t} in particular buffers. | |
455 @end defopt | |
456 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
457 See also the function @code{set-visited-file-name} (@pxref{Buffer File |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
458 Name}). |
15765
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
459 |
6555 | 460 @node Reading from Files |
461 @comment node-name, next, previous, up | |
462 @section Reading from Files | |
463 | |
464 You can copy a file from the disk and insert it into a buffer | |
465 using the @code{insert-file-contents} function. Don't use the user-level | |
466 command @code{insert-file} in a Lisp program, as that sets the mark. | |
467 | |
468 @defun insert-file-contents filename &optional visit beg end replace | |
469 This function inserts the contents of file @var{filename} into the | |
12226 | 470 current buffer after point. It returns a list of the absolute file name |
6555 | 471 and the length of the data inserted. An error is signaled if |
472 @var{filename} is not the name of a file that can be read. | |
473 | |
12098 | 474 The function @code{insert-file-contents} checks the file contents |
475 against the defined file formats, and converts the file contents if | |
476 appropriate. @xref{Format Conversion}. It also calls the functions in | |
477 the list @code{after-insert-file-functions}; see @ref{Saving | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
478 Properties}. Normally, one of the functions in the |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
479 @code{after-insert-file-functions} list determines the coding system |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
480 (@pxref{Coding Systems}) used for decoding the file's contents. |
6555 | 481 |
482 If @var{visit} is non-@code{nil}, this function additionally marks the | |
483 buffer as unmodified and sets up various fields in the buffer so that it | |
484 is visiting the file @var{filename}: these include the buffer's visited | |
485 file name and its last save file modtime. This feature is used by | |
486 @code{find-file-noselect} and you probably should not use it yourself. | |
487 | |
488 If @var{beg} and @var{end} are non-@code{nil}, they should be integers | |
489 specifying the portion of the file to insert. In this case, @var{visit} | |
490 must be @code{nil}. For example, | |
491 | |
492 @example | |
493 (insert-file-contents filename nil 0 500) | |
494 @end example | |
495 | |
496 @noindent | |
497 inserts the first 500 characters of a file. | |
498 | |
499 If the argument @var{replace} is non-@code{nil}, it means to replace the | |
500 contents of the buffer (actually, just the accessible portion) with the | |
501 contents of the file. This is better than simply deleting the buffer | |
502 contents and inserting the whole file, because (1) it preserves some | |
503 marker positions and (2) it puts less data in the undo list. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
504 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
505 It is possible to read a special file (such as a FIFO or an I/O device) |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
506 with @code{insert-file-contents}, as long as @var{replace} and |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
507 @var{visit} are @code{nil}. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
508 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
509 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
510 @defun insert-file-contents-literally filename &optional visit beg end replace |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
511 @tindex insert-file-contents-literally |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
512 This function works like @code{insert-file-contents} except that it does |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
513 not do format decoding (@pxref{Format Conversion}), does not do |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
514 character code conversion (@pxref{Coding Systems}), does not run |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
515 @code{find-file-hooks}, does not perform automatic uncompression, and so |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
516 on. |
6555 | 517 @end defun |
518 | |
519 If you want to pass a file name to another process so that another | |
520 program can read the file, use the function @code{file-local-copy}; see | |
521 @ref{Magic File Names}. | |
522 | |
523 @node Writing to Files | |
524 @comment node-name, next, previous, up | |
525 @section Writing to Files | |
526 | |
527 You can write the contents of a buffer, or part of a buffer, directly | |
528 to a file on disk using the @code{append-to-file} and | |
529 @code{write-region} functions. Don't use these functions to write to | |
530 files that are being visited; that could cause confusion in the | |
531 mechanisms for visiting. | |
532 | |
533 @deffn Command append-to-file start end filename | |
534 This function appends the contents of the region delimited by | |
535 @var{start} and @var{end} in the current buffer to the end of file | |
536 @var{filename}. If that file does not exist, it is created. This | |
537 function returns @code{nil}. | |
538 | |
539 An error is signaled if @var{filename} specifies a nonwritable file, | |
540 or a nonexistent file in a directory where files cannot be created. | |
541 @end deffn | |
542 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
543 @deffn Command write-region start end filename &optional append visit lockname mustbenew |
6555 | 544 This function writes the region delimited by @var{start} and @var{end} |
545 in the current buffer into the file specified by @var{filename}. | |
546 | |
547 @c Emacs 19 feature | |
548 If @var{start} is a string, then @code{write-region} writes or appends | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
549 that string, rather than text from the buffer. @var{end} is ignored in |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
550 this case. |
6555 | 551 |
552 If @var{append} is non-@code{nil}, then the specified text is appended | |
553 to the existing file contents (if any). | |
554 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
555 If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
556 for confirmation if @var{filename} names an existing file. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
557 Starting in Emacs 21, if @var{mustbenew} is the symbol @code{excl}, |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
558 then @code{write-region} does not ask for confirmation, but instead |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
559 it signals an error @code{file-already-exists} if the file already |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
560 exists. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
561 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
562 The test for an existing file, when @var{mustbenew} is @code{excl}, uses |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
563 a special system feature. At least for files on a local disk, there is |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
564 no chance that some other program could create a file of the same name |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
565 before Emacs does, without Emacs's noticing. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
566 |
6555 | 567 If @var{visit} is @code{t}, then Emacs establishes an association |
568 between the buffer and the file: the buffer is then visiting that file. | |
569 It also sets the last file modification time for the current buffer to | |
570 @var{filename}'s modtime, and marks the buffer as not modified. This | |
571 feature is used by @code{save-buffer}, but you probably should not use | |
572 it yourself. | |
573 | |
574 @c Emacs 19 feature | |
575 If @var{visit} is a string, it specifies the file name to visit. This | |
576 way, you can write the data to one file (@var{filename}) while recording | |
577 the buffer as visiting another file (@var{visit}). The argument | |
578 @var{visit} is used in the echo area message and also for file locking; | |
579 @var{visit} is stored in @code{buffer-file-name}. This feature is used | |
580 to implement @code{file-precious-flag}; don't use it yourself unless you | |
581 really know what you're doing. | |
582 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
583 The optional argument @var{lockname}, if non-@code{nil}, specifies the |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
584 file name to use for purposes of locking and unlocking, overriding |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
585 @var{filename} and @var{visit} for that purpose. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
586 |
12098 | 587 The function @code{write-region} converts the data which it writes to |
588 the appropriate file formats specified by @code{buffer-file-format}. | |
589 @xref{Format Conversion}. It also calls the functions in the list | |
590 @code{write-region-annotate-functions}; see @ref{Saving Properties}. | |
6555 | 591 |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
592 Normally, @code{write-region} displays the message @samp{Wrote |
6555 | 593 @var{filename}} in the echo area. If @var{visit} is neither @code{t} |
594 nor @code{nil} nor a string, then this message is inhibited. This | |
595 feature is useful for programs that use files for internal purposes, | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
596 files that the user does not need to know about. |
6555 | 597 @end deffn |
598 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
599 @defmac with-temp-file file body... |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
600 @tindex with-temp-file |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
601 The @code{with-temp-file} macro evaluates the @var{body} forms with a |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
602 temporary buffer as the current buffer; then, at the end, it writes the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
603 buffer contents into file @var{file}. It kills the temporary buffer |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
604 when finished, restoring the buffer that was current before the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
605 @code{with-temp-file} form. Then it returns the value of the last form |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
606 in @var{body}. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
607 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
608 The current buffer is restored even in case of an abnormal exit via |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
609 @code{throw} or error (@pxref{Nonlocal Exits}). |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
610 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
611 See also @code{with-temp-buffer} in @ref{Current Buffer}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
612 @end defmac |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
613 |
6555 | 614 @node File Locks |
615 @section File Locks | |
616 @cindex file locks | |
617 | |
618 When two users edit the same file at the same time, they are likely to | |
619 interfere with each other. Emacs tries to prevent this situation from | |
620 arising by recording a @dfn{file lock} when a file is being modified. | |
621 Emacs can then detect the first attempt to modify a buffer visiting a | |
622 file that is locked by another Emacs job, and ask the user what to do. | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
623 The file lock is really a file, a symbolic link with a special name, |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
624 stored in the same directory as the file you are editing. |
6555 | 625 |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
626 When you access files using NFS, there may be a small probability that |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
627 you and another user will both lock the same file ``simultaneously''. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
628 If this happens, it is possible for the two users to make changes |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
629 simultaneously, but Emacs will still warn the user who saves second. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
630 Also, the detection of modification of a buffer visiting a file changed |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
631 on disk catches some cases of simultaneous editing; see |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
632 @ref{Modification Time}. |
6555 | 633 |
634 @defun file-locked-p filename | |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
635 This function returns @code{nil} if the file @var{filename} is not |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
636 locked. It returns @code{t} if it is locked by this Emacs process, and |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
637 it returns the name of the user who has locked it if it is locked by |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
638 some other job. |
6555 | 639 |
640 @example | |
641 @group | |
642 (file-locked-p "foo") | |
643 @result{} nil | |
644 @end group | |
645 @end example | |
646 @end defun | |
647 | |
648 @defun lock-buffer &optional filename | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
649 This function locks the file @var{filename}, if the current buffer is |
6555 | 650 modified. The argument @var{filename} defaults to the current buffer's |
651 visited file. Nothing is done if the current buffer is not visiting a | |
652 file, or is not modified. | |
653 @end defun | |
654 | |
655 @defun unlock-buffer | |
656 This function unlocks the file being visited in the current buffer, | |
657 if the buffer is modified. If the buffer is not modified, then | |
658 the file should not be locked, so this function does nothing. It also | |
659 does nothing if the current buffer is not visiting a file. | |
660 @end defun | |
661 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
662 File locking is not supported on some systems. On systems that do not |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
663 support it, the functions @code{lock-buffer}, @code{unlock-buffer} and |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
664 @code{file-locked-p} do nothing and return @code{nil}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
665 |
6555 | 666 @defun ask-user-about-lock file other-user |
667 This function is called when the user tries to modify @var{file}, but it | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
668 is locked by another user named @var{other-user}. The default |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
669 definition of this function asks the user to say what to do. The value |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
670 this function returns determines what Emacs does next: |
6555 | 671 |
672 @itemize @bullet | |
673 @item | |
674 A value of @code{t} says to grab the lock on the file. Then | |
675 this user may edit the file and @var{other-user} loses the lock. | |
676 | |
677 @item | |
678 A value of @code{nil} says to ignore the lock and let this | |
679 user edit the file anyway. | |
680 | |
681 @item | |
682 @kindex file-locked | |
683 This function may instead signal a @code{file-locked} error, in which | |
684 case the change that the user was about to make does not take place. | |
685 | |
686 The error message for this error looks like this: | |
687 | |
688 @example | |
689 @error{} File is locked: @var{file} @var{other-user} | |
690 @end example | |
691 | |
692 @noindent | |
693 where @code{file} is the name of the file and @var{other-user} is the | |
694 name of the user who has locked the file. | |
695 @end itemize | |
696 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
697 If you wish, you can replace the @code{ask-user-about-lock} function |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
698 with your own version that makes the decision in another way. The code |
6555 | 699 for its usual definition is in @file{userlock.el}. |
700 @end defun | |
701 | |
702 @node Information about Files | |
703 @section Information about Files | |
704 | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
705 The functions described in this section all operate on strings that |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
706 designate file names. All the functions have names that begin with the |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
707 word @samp{file}. These functions all return information about actual |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
708 files or directories, so their arguments must all exist as actual files |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
709 or directories unless otherwise noted. |
6555 | 710 |
711 @menu | |
712 * Testing Accessibility:: Is a given file readable? Writable? | |
713 * Kinds of Files:: Is it a directory? A symbolic link? | |
714 * Truenames:: Eliminating symbolic links from a file name. | |
715 * File Attributes:: How large is it? Any other names? Etc. | |
716 @end menu | |
717 | |
718 @node Testing Accessibility | |
719 @comment node-name, next, previous, up | |
720 @subsection Testing Accessibility | |
721 @cindex accessibility of a file | |
722 @cindex file accessibility | |
723 | |
724 These functions test for permission to access a file in specific ways. | |
725 | |
726 @defun file-exists-p filename | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
727 This function returns @code{t} if a file named @var{filename} appears to |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
728 exist. This does not mean you can necessarily read the file, only that |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
729 you can find out its attributes. (On Unix and GNU/Linux, this is true |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
730 if the file exists and you have execute permission on the containing |
6555 | 731 directories, regardless of the protection of the file itself.) |
732 | |
733 If the file does not exist, or if fascist access control policies | |
734 prevent you from finding the attributes of the file, this function | |
735 returns @code{nil}. | |
736 @end defun | |
737 | |
738 @defun file-readable-p filename | |
739 This function returns @code{t} if a file named @var{filename} exists | |
740 and you can read it. It returns @code{nil} otherwise. | |
741 | |
742 @example | |
743 @group | |
744 (file-readable-p "files.texi") | |
745 @result{} t | |
746 @end group | |
747 @group | |
748 (file-exists-p "/usr/spool/mqueue") | |
749 @result{} t | |
750 @end group | |
751 @group | |
752 (file-readable-p "/usr/spool/mqueue") | |
753 @result{} nil | |
754 @end group | |
755 @end example | |
756 @end defun | |
757 | |
758 @c Emacs 19 feature | |
759 @defun file-executable-p filename | |
760 This function returns @code{t} if a file named @var{filename} exists and | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
761 you can execute it. It returns @code{nil} otherwise. On Unix and |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
762 GNU/Linux, if the file is a directory, execute permission means you can |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
763 check the existence and attributes of files inside the directory, and |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
764 open those files if their modes permit. |
6555 | 765 @end defun |
766 | |
767 @defun file-writable-p filename | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
768 This function returns @code{t} if the file @var{filename} can be written |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
769 or created by you, and @code{nil} otherwise. A file is writable if the |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
770 file exists and you can write it. It is creatable if it does not exist, |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
771 but the specified directory does exist and you can write in that |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
772 directory. |
6555 | 773 |
774 In the third example below, @file{foo} is not writable because the | |
775 parent directory does not exist, even though the user could create such | |
776 a directory. | |
777 | |
778 @example | |
779 @group | |
780 (file-writable-p "~/foo") | |
781 @result{} t | |
782 @end group | |
783 @group | |
784 (file-writable-p "/foo") | |
785 @result{} nil | |
786 @end group | |
787 @group | |
788 (file-writable-p "~/no-such-dir/foo") | |
789 @result{} nil | |
790 @end group | |
791 @end example | |
792 @end defun | |
793 | |
794 @c Emacs 19 feature | |
795 @defun file-accessible-directory-p dirname | |
796 This function returns @code{t} if you have permission to open existing | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
797 files in the directory whose name as a file is @var{dirname}; otherwise |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
798 (or if there is no such directory), it returns @code{nil}. The value |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
799 of @var{dirname} may be either a directory name or the file name of a |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
800 file which is a directory. |
6555 | 801 |
802 Example: after the following, | |
803 | |
804 @example | |
805 (file-accessible-directory-p "/foo") | |
806 @result{} nil | |
807 @end example | |
808 | |
809 @noindent | |
810 we can deduce that any attempt to read a file in @file{/foo/} will | |
811 give an error. | |
812 @end defun | |
813 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
814 @defun access-file filename string |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
815 @tindex access-file |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
816 This function opens file @var{filename} for reading, then closes it and |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
817 returns @code{nil}. However, if the open fails, it signals an error |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
818 using @var{string} as the error message text. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
819 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
820 |
12067 | 821 @defun file-ownership-preserved-p filename |
822 This function returns @code{t} if deleting the file @var{filename} and | |
823 then creating it anew would keep the file's owner unchanged. | |
824 @end defun | |
825 | |
6555 | 826 @defun file-newer-than-file-p filename1 filename2 |
827 @cindex file age | |
828 @cindex file modification time | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
829 This function returns @code{t} if the file @var{filename1} is |
6555 | 830 newer than file @var{filename2}. If @var{filename1} does not |
831 exist, it returns @code{nil}. If @var{filename2} does not exist, | |
832 it returns @code{t}. | |
833 | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
834 In the following example, assume that the file @file{aug-19} was written |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
835 on the 19th, @file{aug-20} was written on the 20th, and the file |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
836 @file{no-file} doesn't exist at all. |
6555 | 837 |
838 @example | |
839 @group | |
840 (file-newer-than-file-p "aug-19" "aug-20") | |
841 @result{} nil | |
842 @end group | |
843 @group | |
844 (file-newer-than-file-p "aug-20" "aug-19") | |
845 @result{} t | |
846 @end group | |
847 @group | |
848 (file-newer-than-file-p "aug-19" "no-file") | |
849 @result{} t | |
850 @end group | |
851 @group | |
852 (file-newer-than-file-p "no-file" "aug-19") | |
853 @result{} nil | |
854 @end group | |
855 @end example | |
856 | |
857 You can use @code{file-attributes} to get a file's last modification | |
858 time as a list of two numbers. @xref{File Attributes}. | |
859 @end defun | |
860 | |
861 @node Kinds of Files | |
862 @comment node-name, next, previous, up | |
863 @subsection Distinguishing Kinds of Files | |
864 | |
12098 | 865 This section describes how to distinguish various kinds of files, such |
866 as directories, symbolic links, and ordinary files. | |
6555 | 867 |
868 @defun file-symlink-p filename | |
869 @cindex file symbolic links | |
870 If the file @var{filename} is a symbolic link, the @code{file-symlink-p} | |
871 function returns the file name to which it is linked. This may be the | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
872 name of a text file, a directory, or even another symbolic link, or it |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
873 may be a nonexistent file name. |
6555 | 874 |
875 If the file @var{filename} is not a symbolic link (or there is no such file), | |
876 @code{file-symlink-p} returns @code{nil}. | |
877 | |
878 @example | |
879 @group | |
880 (file-symlink-p "foo") | |
881 @result{} nil | |
882 @end group | |
883 @group | |
884 (file-symlink-p "sym-link") | |
885 @result{} "foo" | |
886 @end group | |
887 @group | |
888 (file-symlink-p "sym-link2") | |
889 @result{} "sym-link" | |
890 @end group | |
891 @group | |
892 (file-symlink-p "/bin") | |
893 @result{} "/pub/bin" | |
894 @end group | |
895 @end example | |
896 | |
897 @c !!! file-symlink-p: should show output of ls -l for comparison | |
898 @end defun | |
899 | |
900 @defun file-directory-p filename | |
901 This function returns @code{t} if @var{filename} is the name of an | |
902 existing directory, @code{nil} otherwise. | |
903 | |
904 @example | |
905 @group | |
906 (file-directory-p "~rms") | |
907 @result{} t | |
908 @end group | |
909 @group | |
910 (file-directory-p "~rms/lewis/files.texi") | |
911 @result{} nil | |
912 @end group | |
913 @group | |
914 (file-directory-p "~rms/lewis/no-such-file") | |
915 @result{} nil | |
916 @end group | |
917 @group | |
918 (file-directory-p "$HOME") | |
919 @result{} nil | |
920 @end group | |
921 @group | |
922 (file-directory-p | |
923 (substitute-in-file-name "$HOME")) | |
924 @result{} t | |
925 @end group | |
926 @end example | |
927 @end defun | |
928 | |
12067 | 929 @defun file-regular-p filename |
930 This function returns @code{t} if the file @var{filename} exists and is | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
931 a regular file (not a directory, named pipe, terminal, or |
12067 | 932 other I/O device). |
933 @end defun | |
934 | |
6555 | 935 @node Truenames |
936 @subsection Truenames | |
937 @cindex truename (of file) | |
938 | |
939 @c Emacs 19 features | |
940 The @dfn{truename} of a file is the name that you get by following | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
941 symbolic links at all levels until none remain, then simplifying away |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
942 @samp{.}@: and @samp{..}@: appearing as name components. This results |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
943 in a sort of canonical name for the file. A file does not always have a |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
944 unique truename; the number of distinct truenames a file has is equal to |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
945 the number of hard links to the file. However, truenames are useful |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
946 because they eliminate symbolic links as a cause of name variation. |
6555 | 947 |
948 @defun file-truename filename | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
949 The function @code{file-truename} returns the truename of the file |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
950 @var{filename}. The argument must be an absolute file name. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
951 @end defun |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
952 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
953 @defun file-chase-links filename |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
954 This function follows symbolic links, starting with @var{filename}, |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
955 until it finds a file name which is not the name of a symbolic link. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
956 Then it returns that file name. |
6555 | 957 @end defun |
958 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
959 To illustrate the difference between @code{file-chase-links} and |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
960 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
961 the directory @file{/home/foo}, and @file{/home/foo/hello} is an |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
962 ordinary file (or at least, not a symbolic link) or nonexistent. Then |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
963 we would have: |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
964 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
965 @example |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
966 (file-chase-links "/usr/foo/hello") |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
967 ;; @r{This does not follow the links in the parent directories.} |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
968 @result{} "/usr/foo/hello" |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
969 (file-truename "/usr/foo/hello") |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
970 ;; @r{Assuming that @file{/home} is not a symbolic link.} |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
971 @result{} "/home/foo/hello" |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
972 @end example |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
973 |
6555 | 974 @xref{Buffer File Name}, for related information. |
975 | |
976 @node File Attributes | |
977 @comment node-name, next, previous, up | |
978 @subsection Other Information about Files | |
979 | |
980 This section describes the functions for getting detailed information | |
981 about a file, other than its contents. This information includes the | |
982 mode bits that control access permission, the owner and group numbers, | |
983 the number of names, the inode number, the size, and the times of access | |
984 and modification. | |
985 | |
986 @defun file-modes filename | |
987 @cindex permission | |
988 @cindex file attributes | |
989 This function returns the mode bits of @var{filename}, as an integer. | |
990 The mode bits are also called the file permissions, and they specify | |
991 access control in the usual Unix fashion. If the low-order bit is 1, | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
992 then the file is executable by all users, if the second-lowest-order bit |
6555 | 993 is 1, then the file is writable by all users, etc. |
994 | |
995 The highest value returnable is 4095 (7777 octal), meaning that | |
996 everyone has read, write, and execute permission, that the @sc{suid} bit | |
997 is set for both others and group, and that the sticky bit is set. | |
998 | |
999 @example | |
1000 @group | |
1001 (file-modes "~/junk/diffs") | |
1002 @result{} 492 ; @r{Decimal integer.} | |
1003 @end group | |
1004 @group | |
1005 (format "%o" 492) | |
1006 @result{} "754" ; @r{Convert to octal.} | |
1007 @end group | |
1008 | |
1009 @group | |
1010 (set-file-modes "~/junk/diffs" 438) | |
1011 @result{} nil | |
1012 @end group | |
1013 | |
1014 @group | |
1015 (format "%o" 438) | |
1016 @result{} "666" ; @r{Convert to octal.} | |
1017 @end group | |
1018 | |
1019 @group | |
1020 % ls -l diffs | |
1021 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs | |
1022 @end group | |
1023 @end example | |
1024 @end defun | |
1025 | |
1026 @defun file-nlinks filename | |
1027 This functions returns the number of names (i.e., hard links) that | |
1028 file @var{filename} has. If the file does not exist, then this function | |
1029 returns @code{nil}. Note that symbolic links have no effect on this | |
1030 function, because they are not considered to be names of the files they | |
1031 link to. | |
1032 | |
1033 @example | |
1034 @group | |
1035 % ls -l foo* | |
1036 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo | |
1037 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1 | |
1038 @end group | |
1039 | |
1040 @group | |
1041 (file-nlinks "foo") | |
1042 @result{} 2 | |
1043 @end group | |
1044 @group | |
1045 (file-nlinks "doesnt-exist") | |
1046 @result{} nil | |
1047 @end group | |
1048 @end example | |
1049 @end defun | |
1050 | |
1051 @defun file-attributes filename | |
1052 This function returns a list of attributes of file @var{filename}. If | |
1053 the specified file cannot be opened, it returns @code{nil}. | |
1054 | |
1055 The elements of the list, in order, are: | |
1056 | |
1057 @enumerate 0 | |
1058 @item | |
1059 @code{t} for a directory, a string for a symbolic link (the name | |
1060 linked to), or @code{nil} for a text file. | |
1061 | |
1062 @c Wordy so as to prevent an overfull hbox. --rjc 15mar92 | |
1063 @item | |
1064 The number of names the file has. Alternate names, also known as hard | |
1065 links, can be created by using the @code{add-name-to-file} function | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1066 (@pxref{Changing Files}). |
6555 | 1067 |
1068 @item | |
1069 The file's @sc{uid}. | |
1070 | |
1071 @item | |
1072 The file's @sc{gid}. | |
1073 | |
1074 @item | |
1075 The time of last access, as a list of two integers. | |
1076 The first integer has the high-order 16 bits of time, | |
1077 the second has the low 16 bits. (This is similar to the | |
1078 value of @code{current-time}; see @ref{Time of Day}.) | |
1079 | |
1080 @item | |
1081 The time of last modification as a list of two integers (as above). | |
1082 | |
1083 @item | |
1084 The time of last status change as a list of two integers (as above). | |
1085 | |
1086 @item | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
1087 The size of the file in bytes. If the size is too large to fit in a |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
1088 Lisp integer, this is a floating point number. |
6555 | 1089 |
1090 @item | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1091 The file's modes, as a string of ten letters or dashes, |
6555 | 1092 as in @samp{ls -l}. |
1093 | |
1094 @item | |
1095 @code{t} if the file's @sc{gid} would change if file were | |
1096 deleted and recreated; @code{nil} otherwise. | |
1097 | |
1098 @item | |
17919
eb712b69e495
The inode number can be an integer.
Richard M. Stallman <rms@gnu.org>
parents:
17398
diff
changeset
|
1099 The file's inode number. If possible, this is an integer. If the inode |
eb712b69e495
The inode number can be an integer.
Richard M. Stallman <rms@gnu.org>
parents:
17398
diff
changeset
|
1100 number is too large to be represented as an integer in Emacs Lisp, then |
eb712b69e495
The inode number can be an integer.
Richard M. Stallman <rms@gnu.org>
parents:
17398
diff
changeset
|
1101 the value has the form @code{(@var{high} . @var{low})}, where @var{low} |
eb712b69e495
The inode number can be an integer.
Richard M. Stallman <rms@gnu.org>
parents:
17398
diff
changeset
|
1102 holds the low 16 bits. |
6555 | 1103 |
1104 @item | |
1105 The file system number of the file system that the file is in. This | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1106 element and the file's inode number together give enough information to |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1107 distinguish any two files on the system---no two files can have the same |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1108 values for both of these numbers. |
6555 | 1109 @end enumerate |
1110 | |
1111 For example, here are the file attributes for @file{files.texi}: | |
1112 | |
1113 @example | |
1114 @group | |
1115 (file-attributes "files.texi") | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1116 @result{} (nil 1 2235 75 |
6555 | 1117 (8489 20284) |
1118 (8489 20284) | |
1119 (8489 20285) | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1120 14906 "-rw-rw-rw-" |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1121 nil 129500 -32252) |
6555 | 1122 @end group |
1123 @end example | |
1124 | |
1125 @noindent | |
1126 and here is how the result is interpreted: | |
1127 | |
1128 @table @code | |
1129 @item nil | |
1130 is neither a directory nor a symbolic link. | |
1131 | |
1132 @item 1 | |
1133 has only one name (the name @file{files.texi} in the current default | |
1134 directory). | |
1135 | |
1136 @item 2235 | |
1137 is owned by the user with @sc{uid} 2235. | |
1138 | |
1139 @item 75 | |
1140 is in the group with @sc{gid} 75. | |
1141 | |
1142 @item (8489 20284) | |
12522 | 1143 was last accessed on Aug 19 00:09. |
6555 | 1144 |
1145 @item (8489 20284) | |
1146 was last modified on Aug 19 00:09. | |
1147 | |
1148 @item (8489 20285) | |
1149 last had its inode changed on Aug 19 00:09. | |
1150 | |
1151 @item 14906 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1152 is 14906 bytes long. (It may not contain 14906 characters, though, |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1153 if some of the bytes belong to multibyte sequences.) |
6555 | 1154 |
1155 @item "-rw-rw-rw-" | |
1156 has a mode of read and write access for the owner, group, and world. | |
1157 | |
1158 @item nil | |
1159 would retain the same @sc{gid} if it were recreated. | |
1160 | |
1161 @item 129500 | |
1162 has an inode number of 129500. | |
1163 @item -32252 | |
1164 is on file system number -32252. | |
1165 @end table | |
1166 @end defun | |
1167 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1168 @node Changing Files |
6555 | 1169 @section Changing File Names and Attributes |
1170 @cindex renaming files | |
1171 @cindex copying files | |
1172 @cindex deleting files | |
1173 @cindex linking files | |
1174 @cindex setting modes of files | |
1175 | |
1176 The functions in this section rename, copy, delete, link, and set the | |
1177 modes of files. | |
1178 | |
1179 In the functions that have an argument @var{newname}, if a file by the | |
1180 name of @var{newname} already exists, the actions taken depend on the | |
1181 value of the argument @var{ok-if-already-exists}: | |
1182 | |
1183 @itemize @bullet | |
1184 @item | |
1185 Signal a @code{file-already-exists} error if | |
1186 @var{ok-if-already-exists} is @code{nil}. | |
1187 | |
1188 @item | |
1189 Request confirmation if @var{ok-if-already-exists} is a number. | |
1190 | |
1191 @item | |
1192 Replace the old file without confirmation if @var{ok-if-already-exists} | |
1193 is any other value. | |
1194 @end itemize | |
1195 | |
1196 @defun add-name-to-file oldname newname &optional ok-if-already-exists | |
1197 @cindex file with multiple names | |
1198 @cindex file hard link | |
1199 This function gives the file named @var{oldname} the additional name | |
1200 @var{newname}. This means that @var{newname} becomes a new ``hard | |
1201 link'' to @var{oldname}. | |
1202 | |
1203 In the first part of the following example, we list two files, | |
1204 @file{foo} and @file{foo3}. | |
1205 | |
1206 @example | |
1207 @group | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1208 % ls -li fo* |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1209 81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1210 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 |
6555 | 1211 @end group |
1212 @end example | |
1213 | |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
1214 Now we create a hard link, by calling @code{add-name-to-file}, then list |
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
1215 the files again. This shows two names for one file, @file{foo} and |
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
1216 @file{foo2}. |
6555 | 1217 |
1218 @example | |
1219 @group | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1220 (add-name-to-file "foo" "foo2") |
6555 | 1221 @result{} nil |
1222 @end group | |
1223 | |
1224 @group | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1225 % ls -li fo* |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1226 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1227 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1228 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 |
6555 | 1229 @end group |
1230 @end example | |
1231 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1232 Finally, we evaluate the following: |
6555 | 1233 |
1234 @example | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1235 (add-name-to-file "foo" "foo3" t) |
6555 | 1236 @end example |
1237 | |
1238 @noindent | |
1239 and list the files again. Now there are three names | |
1240 for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old | |
1241 contents of @file{foo3} are lost. | |
1242 | |
1243 @example | |
1244 @group | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1245 (add-name-to-file "foo1" "foo3") |
6555 | 1246 @result{} nil |
1247 @end group | |
1248 | |
1249 @group | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1250 % ls -li fo* |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1251 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1252 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1253 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3 |
6555 | 1254 @end group |
1255 @end example | |
1256 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1257 This function is meaningless on operating systems where multiple names |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1258 for one file are not allowed. Some systems implement multiple names |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1259 by copying the file instead. |
6555 | 1260 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1261 See also @code{file-nlinks} in @ref{File Attributes}. |
6555 | 1262 @end defun |
1263 | |
1264 @deffn Command rename-file filename newname &optional ok-if-already-exists | |
1265 This command renames the file @var{filename} as @var{newname}. | |
1266 | |
1267 If @var{filename} has additional names aside from @var{filename}, it | |
1268 continues to have those names. In fact, adding the name @var{newname} | |
1269 with @code{add-name-to-file} and then deleting @var{filename} has the | |
1270 same effect as renaming, aside from momentary intermediate states. | |
1271 | |
1272 In an interactive call, this function prompts for @var{filename} and | |
1273 @var{newname} in the minibuffer; also, it requests confirmation if | |
1274 @var{newname} already exists. | |
1275 @end deffn | |
1276 | |
1277 @deffn Command copy-file oldname newname &optional ok-if-exists time | |
1278 This command copies the file @var{oldname} to @var{newname}. An | |
1279 error is signaled if @var{oldname} does not exist. | |
1280 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1281 If @var{time} is non-@code{nil}, then this function gives the new file |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1282 the same last-modified time that the old one has. (This works on only |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1283 some operating systems.) If setting the time gets an error, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1284 @code{copy-file} signals a @code{file-date-error} error. |
6555 | 1285 |
1286 In an interactive call, this function prompts for @var{filename} and | |
1287 @var{newname} in the minibuffer; also, it requests confirmation if | |
1288 @var{newname} already exists. | |
1289 @end deffn | |
1290 | |
1291 @deffn Command delete-file filename | |
1292 @pindex rm | |
1293 This command deletes the file @var{filename}, like the shell command | |
1294 @samp{rm @var{filename}}. If the file has multiple names, it continues | |
1295 to exist under the other names. | |
1296 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1297 A suitable kind of @code{file-error} error is signaled if the file does |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1298 not exist, or is not deletable. (On Unix and GNU/Linux, a file is |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1299 deletable if its directory is writable.) |
6555 | 1300 |
1301 See also @code{delete-directory} in @ref{Create/Delete Dirs}. | |
1302 @end deffn | |
1303 | |
1304 @deffn Command make-symbolic-link filename newname &optional ok-if-exists | |
1305 @pindex ln | |
1306 @kindex file-already-exists | |
1307 This command makes a symbolic link to @var{filename}, named | |
1308 @var{newname}. This is like the shell command @samp{ln -s | |
1309 @var{filename} @var{newname}}. | |
1310 | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1311 In an interactive call, this function prompts for @var{filename} and |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1312 @var{newname} in the minibuffer; also, it requests confirmation if |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1313 @var{newname} already exists. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1314 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1315 This function is not available on systems that don't support symbolic |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1316 links. |
6555 | 1317 @end deffn |
1318 | |
1319 @defun define-logical-name varname string | |
1320 This function defines the logical name @var{name} to have the value | |
1321 @var{string}. It is available only on VMS. | |
1322 @end defun | |
1323 | |
1324 @defun set-file-modes filename mode | |
1325 This function sets mode bits of @var{filename} to @var{mode} (which must | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1326 be an integer). Only the low 12 bits of @var{mode} are used. |
6555 | 1327 @end defun |
1328 | |
1329 @c Emacs 19 feature | |
1330 @defun set-default-file-modes mode | |
1331 This function sets the default file protection for new files created by | |
1332 Emacs and its subprocesses. Every file created with Emacs initially has | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1333 this protection. On Unix and GNU/Linux, the default protection is the |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1334 bitwise complement of the ``umask'' value. |
6555 | 1335 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1336 The argument @var{mode} must be an integer. On most systems, only the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1337 low 9 bits of @var{mode} are meaningful. |
6555 | 1338 |
1339 Saving a modified version of an existing file does not count as creating | |
1340 the file; it does not change the file's mode, and does not use the | |
1341 default file protection. | |
1342 @end defun | |
1343 | |
1344 @defun default-file-modes | |
1345 This function returns the current default protection value. | |
1346 @end defun | |
1347 | |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1348 @cindex MS-DOS and file modes |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1349 @cindex file modes and MS-DOS |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1350 On MS-DOS, there is no such thing as an ``executable'' file mode bit. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1351 So Emacs considers a file executable if its name ends in one of the |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1352 standard executable extensions, such as @file{.com}, @file{.bat}, |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1353 @file{.exe}, and some others. Files that begin with the Unix-standard |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1354 @samp{#!} signature, such as shell and Perl scripts, are also considered |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1355 as executable files. This is reflected in the values returned by |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1356 @code{file-modes} and @code{file-attributes}. Directories are also |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1357 reported with executable bit set, for compatibility with Unix. |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1358 |
6555 | 1359 @node File Names |
1360 @section File Names | |
1361 @cindex file names | |
1362 | |
1363 Files are generally referred to by their names, in Emacs as elsewhere. | |
1364 File names in Emacs are represented as strings. The functions that | |
1365 operate on a file all expect a file name argument. | |
1366 | |
1367 In addition to operating on files themselves, Emacs Lisp programs | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1368 often need to operate on file names; i.e., to take them apart and to use |
6555 | 1369 part of a name to construct related file names. This section describes |
1370 how to manipulate file names. | |
1371 | |
1372 The functions in this section do not actually access files, so they | |
1373 can operate on file names that do not refer to an existing file or | |
1374 directory. | |
1375 | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1376 On VMS, all these functions understand both VMS file-name syntax and |
6555 | 1377 Unix syntax. This is so that all the standard Lisp libraries can |
1378 specify file names in Unix syntax and work properly on VMS without | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1379 change. On MS-DOS and MS-Windows, these functions understand MS-DOS or |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1380 MS-Windows file-name syntax as well as Unix syntax. |
6555 | 1381 |
1382 @menu | |
1383 * File Name Components:: The directory part of a file name, and the rest. | |
1384 * Directory Names:: A directory's name as a directory | |
1385 is different from its name as a file. | |
1386 * Relative File Names:: Some file names are relative to a current directory. | |
1387 * File Name Expansion:: Converting relative file names to absolute ones. | |
1388 * Unique File Names:: Generating names for temporary files. | |
1389 * File Name Completion:: Finding the completions for a given file name. | |
15765
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1390 * Standard File Names:: If your package uses a fixed file name, |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1391 how to handle various operating systems simply. |
6555 | 1392 @end menu |
1393 | |
1394 @node File Name Components | |
1395 @subsection File Name Components | |
1396 @cindex directory part (of file name) | |
1397 @cindex nondirectory part (of file name) | |
1398 @cindex version number (in file name) | |
1399 | |
1400 The operating system groups files into directories. To specify a | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1401 file, you must specify the directory and the file's name within that |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1402 directory. Therefore, Emacs considers a file name as having two main |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1403 parts: the @dfn{directory name} part, and the @dfn{nondirectory} part |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1404 (or @dfn{file name within the directory}). Either part may be empty. |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1405 Concatenating these two parts reproduces the original file name. |
6555 | 1406 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1407 On most systems, the directory part is everything up to and including |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1408 the last slash; the nondirectory part is the rest. The rules in VMS |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1409 syntax are complicated. |
6555 | 1410 |
1411 For some purposes, the nondirectory part is further subdivided into | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1412 the name proper and the @dfn{version number}. On most systems, only |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1413 backup files have version numbers in their names. On VMS, every file |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1414 has a version number, but most of the time the file name actually used |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1415 in Emacs omits the version number, so that version numbers in Emacs are |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1416 found mostly in directory lists. |
6555 | 1417 |
1418 @defun file-name-directory filename | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1419 This function returns the directory part of @var{filename} (or |
6555 | 1420 @code{nil} if @var{filename} does not include a directory part). On |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1421 most systems, the function returns a string ending in a slash. On VMS, |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1422 it returns a string ending in one of the three characters @samp{:}, |
6555 | 1423 @samp{]}, or @samp{>}. |
1424 | |
1425 @example | |
1426 @group | |
1427 (file-name-directory "lewis/foo") ; @r{Unix example} | |
1428 @result{} "lewis/" | |
1429 @end group | |
1430 @group | |
1431 (file-name-directory "foo") ; @r{Unix example} | |
1432 @result{} nil | |
1433 @end group | |
1434 @group | |
1435 (file-name-directory "[X]FOO.TMP") ; @r{VMS example} | |
1436 @result{} "[X]" | |
1437 @end group | |
1438 @end example | |
1439 @end defun | |
1440 | |
1441 @defun file-name-nondirectory filename | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1442 This function returns the nondirectory part of @var{filename}. |
6555 | 1443 |
1444 @example | |
1445 @group | |
1446 (file-name-nondirectory "lewis/foo") | |
1447 @result{} "foo" | |
1448 @end group | |
1449 @group | |
1450 (file-name-nondirectory "foo") | |
1451 @result{} "foo" | |
1452 @end group | |
1453 @group | |
1454 ;; @r{The following example is accurate only on VMS.} | |
1455 (file-name-nondirectory "[X]FOO.TMP") | |
1456 @result{} "FOO.TMP" | |
1457 @end group | |
1458 @end example | |
1459 @end defun | |
1460 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1461 @defun file-name-sans-versions filename &optional keep-backup-version |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1462 This function returns @var{filename} with any file version numbers, |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1463 backup version numbers, or trailing tildes discarded. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1464 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1465 If @var{keep-backup-version} is non-@code{nil}, then true file version |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1466 numbers understood as such by the file system are discarded from the |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1467 return value, but backup version numbers are kept. |
6555 | 1468 |
1469 @example | |
1470 @group | |
1471 (file-name-sans-versions "~rms/foo.~1~") | |
1472 @result{} "~rms/foo" | |
1473 @end group | |
1474 @group | |
1475 (file-name-sans-versions "~rms/foo~") | |
1476 @result{} "~rms/foo" | |
1477 @end group | |
1478 @group | |
1479 (file-name-sans-versions "~rms/foo") | |
1480 @result{} "~rms/foo" | |
1481 @end group | |
1482 @group | |
1483 ;; @r{The following example applies to VMS only.} | |
1484 (file-name-sans-versions "foo;23") | |
1485 @result{} "foo" | |
1486 @end group | |
1487 @end example | |
1488 @end defun | |
1489 | |
12067 | 1490 @defun file-name-sans-extension filename |
12098 | 1491 This function returns @var{filename} minus its ``extension,'' if any. |
1492 The extension, in a file name, is the part that starts with the last | |
1493 @samp{.} in the last name component. For example, | |
1494 | |
1495 @example | |
1496 (file-name-sans-extension "foo.lose.c") | |
1497 @result{} "foo.lose" | |
1498 (file-name-sans-extension "big.hack/foo") | |
1499 @result{} "big.hack/foo" | |
1500 @end example | |
12067 | 1501 @end defun |
1502 | |
6555 | 1503 @node Directory Names |
1504 @comment node-name, next, previous, up | |
1505 @subsection Directory Names | |
1506 @cindex directory name | |
1507 @cindex file name of directory | |
1508 | |
1509 A @dfn{directory name} is the name of a directory. A directory is a | |
1510 kind of file, and it has a file name, which is related to the directory | |
1511 name but not identical to it. (This is not quite the same as the usual | |
1512 Unix terminology.) These two different names for the same entity are | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1513 related by a syntactic transformation. On most systems, this is simple: a |
6555 | 1514 directory name ends in a slash, whereas the directory's name as a file |
1515 lacks that slash. On VMS, the relationship is more complicated. | |
1516 | |
1517 The difference between a directory name and its name as a file is | |
1518 subtle but crucial. When an Emacs variable or function argument is | |
1519 described as being a directory name, a file name of a directory is not | |
1520 acceptable. | |
1521 | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1522 The following two functions convert between directory names and file |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1523 names. They do nothing special with environment variable substitutions |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1524 such as @samp{$HOME}, and the constructs @samp{~}, and @samp{..}. |
6555 | 1525 |
1526 @defun file-name-as-directory filename | |
1527 This function returns a string representing @var{filename} in a form | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1528 that the operating system will interpret as the name of a directory. On |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1529 most systems, this means appending a slash to the string (if it does not |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1530 already end in one). On VMS, the function converts a string of the form |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1531 @file{[X]Y.DIR.1} to the form @file{[X.Y]}. |
6555 | 1532 |
1533 @example | |
1534 @group | |
1535 (file-name-as-directory "~rms/lewis") | |
1536 @result{} "~rms/lewis/" | |
1537 @end group | |
1538 @end example | |
1539 @end defun | |
1540 | |
1541 @defun directory-file-name dirname | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1542 This function returns a string representing @var{dirname} in a form that |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1543 the operating system will interpret as the name of a file. On most |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1544 systems, this means removing the final slash from the string. On VMS, |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1545 the function converts a string of the form @file{[X.Y]} to |
6555 | 1546 @file{[X]Y.DIR.1}. |
1547 | |
1548 @example | |
1549 @group | |
1550 (directory-file-name "~lewis/") | |
1551 @result{} "~lewis" | |
1552 @end group | |
1553 @end example | |
1554 @end defun | |
1555 | |
1556 @cindex directory name abbreviation | |
1557 Directory name abbreviations are useful for directories that are | |
1558 normally accessed through symbolic links. Sometimes the users recognize | |
1559 primarily the link's name as ``the name'' of the directory, and find it | |
1560 annoying to see the directory's ``real'' name. If you define the link | |
1561 name as an abbreviation for the ``real'' name, Emacs shows users the | |
1562 abbreviation instead. | |
1563 | |
1564 @defvar directory-abbrev-alist | |
1565 The variable @code{directory-abbrev-alist} contains an alist of | |
1566 abbreviations to use for file directories. Each element has the form | |
1567 @code{(@var{from} . @var{to})}, and says to replace @var{from} with | |
1568 @var{to} when it appears in a directory name. The @var{from} string is | |
1569 actually a regular expression; it should always start with @samp{^}. | |
1570 The function @code{abbreviate-file-name} performs these substitutions. | |
1571 | |
1572 You can set this variable in @file{site-init.el} to describe the | |
1573 abbreviations appropriate for your site. | |
1574 | |
1575 Here's an example, from a system on which file system @file{/home/fsf} | |
1576 and so on are normally accessed through symbolic links named @file{/fsf} | |
1577 and so on. | |
1578 | |
1579 @example | |
1580 (("^/home/fsf" . "/fsf") | |
1581 ("^/home/gp" . "/gp") | |
1582 ("^/home/gd" . "/gd")) | |
1583 @end example | |
1584 @end defvar | |
1585 | |
1586 To convert a directory name to its abbreviation, use this | |
1587 function: | |
1588 | |
1589 @defun abbreviate-file-name dirname | |
1590 This function applies abbreviations from @code{directory-abbrev-alist} | |
1591 to its argument, and substitutes @samp{~} for the user's home | |
1592 directory. | |
1593 @end defun | |
1594 | |
1595 @node Relative File Names | |
1596 @subsection Absolute and Relative File Names | |
1597 @cindex absolute file name | |
1598 @cindex relative file name | |
1599 | |
1600 All the directories in the file system form a tree starting at the | |
1601 root directory. A file name can specify all the directory names | |
1602 starting from the root of the tree; then it is called an @dfn{absolute} | |
1603 file name. Or it can specify the position of the file in the tree | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1604 relative to a default directory; then it is called a @dfn{relative} file |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1605 name. On Unix and GNU/Linux, an absolute file name starts with a slash |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1606 or a tilde (@samp{~}), and a relative one does not. On MS-DOS and |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1607 MS-Windows, an absolute file name starts with a slash or a backslash, or |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1608 with a drive specification @samp{@var{x}:/}, where @var{x} is the |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1609 @dfn{drive letter}. The rules on VMS are complicated. |
6555 | 1610 |
1611 @defun file-name-absolute-p filename | |
1612 This function returns @code{t} if file @var{filename} is an absolute | |
1613 file name, @code{nil} otherwise. On VMS, this function understands both | |
1614 Unix syntax and VMS syntax. | |
1615 | |
1616 @example | |
1617 @group | |
1618 (file-name-absolute-p "~rms/foo") | |
1619 @result{} t | |
1620 @end group | |
1621 @group | |
1622 (file-name-absolute-p "rms/foo") | |
1623 @result{} nil | |
1624 @end group | |
1625 @group | |
1626 (file-name-absolute-p "/user/rms/foo") | |
1627 @result{} t | |
1628 @end group | |
1629 @end example | |
1630 @end defun | |
1631 | |
1632 @node File Name Expansion | |
1633 @subsection Functions that Expand Filenames | |
1634 @cindex expansion of file names | |
1635 | |
1636 @dfn{Expansion} of a file name means converting a relative file name | |
1637 to an absolute one. Since this is done relative to a default directory, | |
1638 you must specify the default directory name as well as the file name to | |
1639 be expanded. Expansion also simplifies file names by eliminating | |
1640 redundancies such as @file{./} and @file{@var{name}/../}. | |
1641 | |
1642 @defun expand-file-name filename &optional directory | |
1643 This function converts @var{filename} to an absolute file name. If | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1644 @var{directory} is supplied, it is the default directory to start with |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1645 if @var{filename} is relative. (The value of @var{directory} should |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1646 itself be an absolute directory name; it may start with @samp{~}.) |
6555 | 1647 Otherwise, the current buffer's value of @code{default-directory} is |
1648 used. For example: | |
1649 | |
1650 @example | |
1651 @group | |
1652 (expand-file-name "foo") | |
1653 @result{} "/xcssun/users/rms/lewis/foo" | |
1654 @end group | |
1655 @group | |
1656 (expand-file-name "../foo") | |
1657 @result{} "/xcssun/users/rms/foo" | |
1658 @end group | |
1659 @group | |
1660 (expand-file-name "foo" "/usr/spool/") | |
1661 @result{} "/usr/spool/foo" | |
1662 @end group | |
1663 @group | |
1664 (expand-file-name "$HOME/foo") | |
1665 @result{} "/xcssun/users/rms/lewis/$HOME/foo" | |
1666 @end group | |
1667 @end example | |
1668 | |
1669 Filenames containing @samp{.} or @samp{..} are simplified to their | |
1670 canonical form: | |
1671 | |
1672 @example | |
1673 @group | |
1674 (expand-file-name "bar/../foo") | |
1675 @result{} "/xcssun/users/rms/lewis/foo" | |
1676 @end group | |
1677 @end example | |
1678 | |
1679 Note that @code{expand-file-name} does @emph{not} expand environment | |
1680 variables; only @code{substitute-in-file-name} does that. | |
1681 @end defun | |
1682 | |
1683 @c Emacs 19 feature | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1684 @defun file-relative-name filename &optional directory |
6555 | 1685 This function does the inverse of expansion---it tries to return a |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1686 relative name that is equivalent to @var{filename} when interpreted |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1687 relative to @var{directory}. If @var{directory} is omitted or |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1688 @code{nil}, it defaults to the current buffer's default directory. |
17398
a5d9cbc4e2c5
(file-relative-name): Say correctly when the value is absolute.
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
1689 |
a5d9cbc4e2c5
(file-relative-name): Say correctly when the value is absolute.
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
1690 On some operating systems, an absolute file name begins with a device |
a5d9cbc4e2c5
(file-relative-name): Say correctly when the value is absolute.
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
1691 name. On such systems, @var{filename} has no relative equivalent based |
a5d9cbc4e2c5
(file-relative-name): Say correctly when the value is absolute.
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
1692 on @var{directory} if they start with two different device names. In |
a5d9cbc4e2c5
(file-relative-name): Say correctly when the value is absolute.
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
1693 this case, @code{file-relative-name} returns @var{filename} in absolute |
a5d9cbc4e2c5
(file-relative-name): Say correctly when the value is absolute.
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
1694 form. |
6555 | 1695 |
1696 @example | |
1697 (file-relative-name "/foo/bar" "/foo/") | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1698 @result{} "bar" |
6555 | 1699 (file-relative-name "/foo/bar" "/hack/") |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1700 @result{} "/foo/bar" |
6555 | 1701 @end example |
1702 @end defun | |
1703 | |
1704 @defvar default-directory | |
1705 The value of this buffer-local variable is the default directory for the | |
1706 current buffer. It should be an absolute directory name; it may start | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1707 with @samp{~}. This variable is buffer-local in every buffer. |
6555 | 1708 |
1709 @code{expand-file-name} uses the default directory when its second | |
1710 argument is @code{nil}. | |
1711 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1712 Aside from VMS, the value is always a string ending with a slash. |
6555 | 1713 |
1714 @example | |
1715 @group | |
1716 default-directory | |
1717 @result{} "/user/lewis/manual/" | |
1718 @end group | |
1719 @end example | |
1720 @end defvar | |
1721 | |
1722 @defun substitute-in-file-name filename | |
1723 This function replaces environment variables references in | |
1724 @var{filename} with the environment variable values. Following standard | |
1725 Unix shell syntax, @samp{$} is the prefix to substitute an environment | |
1726 variable value. | |
1727 | |
1728 The environment variable name is the series of alphanumeric characters | |
1729 (including underscores) that follow the @samp{$}. If the character following | |
1730 the @samp{$} is a @samp{@{}, then the variable name is everything up to the | |
1731 matching @samp{@}}. | |
1732 | |
1733 @c Wordy to avoid overfull hbox. --rjc 15mar92 | |
1734 Here we assume that the environment variable @code{HOME}, which holds | |
1735 the user's home directory name, has value @samp{/xcssun/users/rms}. | |
1736 | |
1737 @example | |
1738 @group | |
1739 (substitute-in-file-name "$HOME/foo") | |
1740 @result{} "/xcssun/users/rms/foo" | |
1741 @end group | |
1742 @end example | |
1743 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1744 After substitution, if a @samp{~} or a @samp{/} appears following a |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1745 @samp{/}, everything before the following @samp{/} is discarded: |
6555 | 1746 |
1747 @example | |
1748 @group | |
1749 (substitute-in-file-name "bar/~/foo") | |
1750 @result{} "~/foo" | |
1751 @end group | |
1752 @group | |
1753 (substitute-in-file-name "/usr/local/$HOME/foo") | |
1754 @result{} "/xcssun/users/rms/foo" | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1755 ;; @r{@file{/usr/local/} has been discarded.} |
6555 | 1756 @end group |
1757 @end example | |
1758 | |
1759 On VMS, @samp{$} substitution is not done, so this function does nothing | |
1760 on VMS except discard superfluous initial components as shown above. | |
1761 @end defun | |
1762 | |
1763 @node Unique File Names | |
1764 @subsection Generating Unique File Names | |
1765 | |
1766 Some programs need to write temporary files. Here is the usual way to | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1767 construct a name for such a file, starting in Emacs 21: |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1768 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1769 @example |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1770 (make-temp-file @var{name-of-application}) |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1771 @end example |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1772 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1773 @noindent |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1774 The job of @code{make-temp-file} is to prevent two different users or |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1775 two different jobs from trying to use the exact same file name. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1776 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1777 @defun make-temp-file prefix &optional dir-flag |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1778 @tindex make-temp-file |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1779 This function creates a temporary file and returns its name. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1780 The name starts with @var{prefix}; it also contains a number that is |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1781 different in each Emacs job. If @var{prefix} is a relative file name, |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1782 it is expanded against @code{temporary-file-directory}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1783 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1784 @example |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1785 @group |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1786 (make-temp-file "foo") |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1787 @result{} "/tmp/foo232J6v" |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1788 @end group |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1789 @end example |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1790 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1791 When @code{make-temp-file} returns, the file has been created and is |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1792 empty. At that point, you should write the intended contents into the |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1793 file. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1794 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1795 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1796 an empty directory instead of an empty file. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1797 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1798 To prevent conflicts among different libraries running in the same |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1799 Emacs, each Lisp program that uses @code{make-temp-file} should have its |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1800 own @var{prefix}. The number added to the end of @var{prefix} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1801 distinguishes between the same application running in different Emacs |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1802 jobs. Additional added characters permit a large number of distinct |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1803 names even in one Emacs job. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1804 @end defun |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1805 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1806 The default directory for temporary files is controlled by the |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1807 variable @code{temporary-file-directory}. This variable gives the user |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1808 a uniform way to specify the directory for all temporary files. Some |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1809 programs use @code{small-temporary-file-directory} instead, if that is |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1810 non-@code{nil}. To use it, you should expand the prefix against |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1811 the proper directory before calling @code{make-temp-file}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1812 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1813 In older Emacs versions where @code{make-temp-file} does not exist, |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1814 you should use @code{make-temp-name} instead: |
6555 | 1815 |
1816 @example | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1817 (make-temp-name |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1818 (expand-file-name @var{name-of-application} |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1819 temporary-file-directory)) |
6555 | 1820 @end example |
1821 | |
1822 @defun make-temp-name string | |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1823 This function generates a string that can be used as a unique file name. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1824 The name starts with @var{string}, and contains a number that is |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1825 different in each Emacs job. It is like @code{make-temp-file} except |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1826 that it just constructs a name, and does not create a file. On MS-DOS, |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1827 the @var{string} prefix can be truncated to fit into the 8+3 file-name |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1828 limits. |
6555 | 1829 @end defun |
1830 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1831 @defvar temporary-file-directory |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1832 @cindex @code{TMPDIR} environment variable |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1833 @cindex @code{TMP} environment variable |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1834 @cindex @code{TEMP} environment variable |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1835 This variable specifies the directory name for creating temporary files. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1836 Its value should be a directory name (@pxref{Directory Names}), but it |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1837 is good for Lisp programs to cope if the value is a directory's file |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1838 name instead. Using the value as the second argument to |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1839 @code{expand-file-name} is a good way to achieve that. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1840 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1841 The default value is determined in a reasonable way for your operating |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1842 system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1843 environment variables, with a fall-back to a system-dependent name if |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1844 none of these variables is defined. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1845 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1846 Even if you do not use @code{make-temp-name} to choose the temporary |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1847 file's name, you should still use this variable to decide which |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1848 directory to put the file in. However, if you expect the file to be |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1849 small, you should use @code{small-temporary-file-directory} first if |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1850 that is non-@code{nil}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1851 @end defvar |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1852 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1853 @tindex small-temporary-file-directory |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1854 @defvar small-temporary-file-directory |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1855 This variable (new in Emacs 21) specifies the directory name for |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1856 creating certain temporary files, which are likely to be small. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1857 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1858 If you want to write a temporary file which is likely to be small, you |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1859 should compute the directory like this: |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1860 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1861 @example |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1862 (make-temp-file |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1863 (expand-file-name @var{prefix} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1864 (or small-temporary-file-directory |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1865 temporary-file-directory))) |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1866 @end example |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1867 @end defvar |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1868 |
6555 | 1869 @node File Name Completion |
1870 @subsection File Name Completion | |
1871 @cindex file name completion subroutines | |
1872 @cindex completion, file name | |
1873 | |
1874 This section describes low-level subroutines for completing a file | |
1875 name. For other completion functions, see @ref{Completion}. | |
1876 | |
1877 @defun file-name-all-completions partial-filename directory | |
1878 This function returns a list of all possible completions for a file | |
1879 whose name starts with @var{partial-filename} in directory | |
1880 @var{directory}. The order of the completions is the order of the files | |
1881 in the directory, which is unpredictable and conveys no useful | |
1882 information. | |
1883 | |
1884 The argument @var{partial-filename} must be a file name containing no | |
1885 directory part and no slash. The current buffer's default directory is | |
1886 prepended to @var{directory}, if @var{directory} is not absolute. | |
1887 | |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
1888 In the following example, suppose that @file{~rms/lewis} is the current |
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
1889 default directory, and has five files whose names begin with @samp{f}: |
6555 | 1890 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and |
1891 @file{file.c.~2~}.@refill | |
1892 | |
1893 @example | |
1894 @group | |
1895 (file-name-all-completions "f" "") | |
1896 @result{} ("foo" "file~" "file.c.~2~" | |
1897 "file.c.~1~" "file.c") | |
1898 @end group | |
1899 | |
1900 @group | |
1901 (file-name-all-completions "fo" "") | |
1902 @result{} ("foo") | |
1903 @end group | |
1904 @end example | |
1905 @end defun | |
1906 | |
1907 @defun file-name-completion filename directory | |
1908 This function completes the file name @var{filename} in directory | |
1909 @var{directory}. It returns the longest prefix common to all file names | |
1910 in directory @var{directory} that start with @var{filename}. | |
1911 | |
1912 If only one match exists and @var{filename} matches it exactly, the | |
1913 function returns @code{t}. The function returns @code{nil} if directory | |
1914 @var{directory} contains no name starting with @var{filename}. | |
1915 | |
1916 In the following example, suppose that the current default directory | |
1917 has five files whose names begin with @samp{f}: @file{foo}, | |
1918 @file{file~}, @file{file.c}, @file{file.c.~1~}, and | |
1919 @file{file.c.~2~}.@refill | |
1920 | |
1921 @example | |
1922 @group | |
1923 (file-name-completion "fi" "") | |
1924 @result{} "file" | |
1925 @end group | |
1926 | |
1927 @group | |
1928 (file-name-completion "file.c.~1" "") | |
1929 @result{} "file.c.~1~" | |
1930 @end group | |
1931 | |
1932 @group | |
1933 (file-name-completion "file.c.~1~" "") | |
1934 @result{} t | |
1935 @end group | |
1936 | |
1937 @group | |
1938 (file-name-completion "file.c.~3" "") | |
1939 @result{} nil | |
1940 @end group | |
1941 @end example | |
1942 @end defun | |
1943 | |
1944 @defopt completion-ignored-extensions | |
1945 @code{file-name-completion} usually ignores file names that end in any | |
1946 string in this list. It does not ignore them when all the possible | |
1947 completions end in one of these suffixes or when a buffer showing all | |
1948 possible completions is displayed.@refill | |
1949 | |
1950 A typical value might look like this: | |
1951 | |
1952 @example | |
1953 @group | |
1954 completion-ignored-extensions | |
1955 @result{} (".o" ".elc" "~" ".dvi") | |
1956 @end group | |
1957 @end example | |
1958 @end defopt | |
1959 | |
15765
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1960 @node Standard File Names |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1961 @subsection Standard File Names |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1962 |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1963 Most of the file names used in Lisp programs are entered by the user. |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1964 But occasionally a Lisp program needs to specify a standard file name |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1965 for a particular use---typically, to hold customization information |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1966 about each user. For example, abbrev definitions are stored (by |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1967 default) in the file @file{~/.abbrev_defs}; the @code{completion} |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1968 package stores completions in the file @file{~/.completions}. These are |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1969 two of the many standard file names used by parts of Emacs for certain |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1970 purposes. |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1971 |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1972 Various operating systems have their own conventions for valid file |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1973 names and for which file names to use for user profile data. A Lisp |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1974 program which reads a file using a standard file name ought to use, on |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1975 each type of system, a file name suitable for that system. The function |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1976 @code{convert-standard-filename} makes this easy to do. |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1977 |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1978 @defun convert-standard-filename filename |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1979 This function alters the file name @var{filename} to fit the conventions |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1980 of the operating system in use, and returns the result as a new string. |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1981 @end defun |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1982 |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1983 The recommended way to specify a standard file name in a Lisp program |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1984 is to choose a name which fits the conventions of GNU and Unix systems, |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1985 usually with a nondirectory part that starts with a period, and pass it |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1986 to @code{convert-standard-filename} instead of using it directly. Here |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1987 is an example from the @code{completion} package: |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1988 |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1989 @example |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1990 (defvar save-completions-file-name |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1991 (convert-standard-filename "~/.completions") |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1992 "*The file name to save completions to.") |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1993 @end example |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1994 |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1995 On GNU and Unix systems, and on some other systems as well, |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1996 @code{convert-standard-filename} returns its argument unchanged. On |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1997 some other systems, it alters the name to fit the system's conventions. |
15765
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1998 |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1999 For example, on MS-DOS the alterations made by this function include |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2000 converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2001 middle of the name to @samp{.} if there is no other @samp{.}, inserting |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2002 a @samp{.} after eight characters if there is none, and truncating to |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2003 three characters after the @samp{.}. (It makes other changes as well.) |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2004 Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2005 @file{.completions} becomes @file{_complet.ion}. |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2006 |
6555 | 2007 @node Contents of Directories |
2008 @section Contents of Directories | |
2009 @cindex directory-oriented functions | |
2010 @cindex file names in directory | |
2011 | |
2012 A directory is a kind of file that contains other files entered under | |
2013 various names. Directories are a feature of the file system. | |
2014 | |
2015 Emacs can list the names of the files in a directory as a Lisp list, | |
2016 or display the names in a buffer using the @code{ls} shell command. In | |
2017 the latter case, it can optionally display information about each file, | |
2018 depending on the options passed to the @code{ls} command. | |
2019 | |
2020 @defun directory-files directory &optional full-name match-regexp nosort | |
2021 This function returns a list of the names of the files in the directory | |
2022 @var{directory}. By default, the list is in alphabetical order. | |
2023 | |
2024 If @var{full-name} is non-@code{nil}, the function returns the files' | |
2025 absolute file names. Otherwise, it returns the names relative to | |
2026 the specified directory. | |
2027 | |
2028 If @var{match-regexp} is non-@code{nil}, this function returns only | |
2029 those file names that contain a match for that regular expression---the | |
2030 other file names are excluded from the list. | |
2031 | |
2032 @c Emacs 19 feature | |
2033 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort | |
2034 the list, so you get the file names in no particular order. Use this if | |
2035 you want the utmost possible speed and don't care what order the files | |
2036 are processed in. If the order of processing is visible to the user, | |
2037 then the user will probably be happier if you do sort the names. | |
2038 | |
2039 @example | |
2040 @group | |
2041 (directory-files "~lewis") | |
2042 @result{} ("#foo#" "#foo.el#" "." ".." | |
2043 "dired-mods.el" "files.texi" | |
2044 "files.texi.~1~") | |
2045 @end group | |
2046 @end example | |
2047 | |
2048 An error is signaled if @var{directory} is not the name of a directory | |
2049 that can be read. | |
2050 @end defun | |
2051 | |
2052 @defun file-name-all-versions file dirname | |
2053 This function returns a list of all versions of the file named | |
2054 @var{file} in directory @var{dirname}. | |
2055 @end defun | |
2056 | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2057 @tindex file-expand-wildcards |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2058 @defun file-expand-wildcards pattern &optional full |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2059 This function expands the wildcard pattern @var{pattern}, returning |
24952 | 2060 a list of file names that match it. |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2061 |
24952 | 2062 If @var{pattern} is written as an absolute file name, |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2063 the values are absolute also. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2064 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2065 If @var{pattern} is written as a relative file name, it is interpreted |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2066 relative to the current default directory. The file names returned are |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2067 normally also relative to the current default directory. However, if |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2068 @var{full} is non-@code{nil}, they are absolute. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2069 @end defun |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2070 |
6555 | 2071 @defun insert-directory file switches &optional wildcard full-directory-p |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2072 This function inserts (in the current buffer) a directory listing for |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2073 directory @var{file}, formatted with @code{ls} according to |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2074 @var{switches}. It leaves point after the inserted text. |
6555 | 2075 |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2076 The argument @var{file} may be either a directory name or a file |
6555 | 2077 specification including wildcard characters. If @var{wildcard} is |
2078 non-@code{nil}, that means treat @var{file} as a file specification with | |
2079 wildcards. | |
2080 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2081 If @var{full-directory-p} is non-@code{nil}, that means the directory |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2082 listing is expected to show the full contents of a directory. You |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2083 should specify @code{t} when @var{file} is a directory and switches do |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2084 not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2085 describe a directory itself as a file, rather than showing its |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2086 contents.) |
6555 | 2087 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2088 On most systems, this function works by running a directory listing |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2089 program whose name is in the variable @code{insert-directory-program}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2090 If @var{wildcard} is non-@code{nil}, it also runs the shell specified by |
6555 | 2091 @code{shell-file-name}, to expand the wildcards. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2092 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2093 MS-DOS and MS-Windows systems usually lack the standard Unix program |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2094 @code{ls}, so this function emulates the standard Unix program @code{ls} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2095 with Lisp code. |
6555 | 2096 @end defun |
2097 | |
2098 @defvar insert-directory-program | |
2099 This variable's value is the program to run to generate a directory listing | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2100 for the function @code{insert-directory}. It is ignored on systems |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2101 which generate the listing with Lisp code. |
6555 | 2102 @end defvar |
2103 | |
2104 @node Create/Delete Dirs | |
2105 @section Creating and Deleting Directories | |
2106 @c Emacs 19 features | |
2107 | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2108 Most Emacs Lisp file-manipulation functions get errors when used on |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2109 files that are directories. For example, you cannot delete a directory |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2110 with @code{delete-file}. These special functions exist to create and |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2111 delete directories. |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2112 |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
2113 @defun make-directory dirname &optional parents |
6555 | 2114 This function creates a directory named @var{dirname}. |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
2115 If @var{parents} is non-@code{nil}, that means to create |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
2116 the parent directories first, if they don't already exist. |
6555 | 2117 @end defun |
2118 | |
2119 @defun delete-directory dirname | |
2120 This function deletes the directory named @var{dirname}. The function | |
2121 @code{delete-file} does not work for files that are directories; you | |
12098 | 2122 must use @code{delete-directory} for them. If the directory contains |
2123 any files, @code{delete-directory} signals an error. | |
6555 | 2124 @end defun |
2125 | |
2126 @node Magic File Names | |
2127 @section Making Certain File Names ``Magic'' | |
2128 @cindex magic file names | |
2129 | |
2130 @c Emacs 19 feature | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2131 You can implement special handling for certain file names. This is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2132 called making those names @dfn{magic}. The principal use for this |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2133 feature is in implementing remote file names (@pxref{Remote Files,, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2134 Remote Files, emacs, The GNU Emacs Manual}). |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2135 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2136 To define a kind of magic file name, you must supply a regular |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2137 expression to define the class of names (all those that match the |
6555 | 2138 regular expression), plus a handler that implements all the primitive |
2139 Emacs file operations for file names that do match. | |
2140 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2141 The variable @code{file-name-handler-alist} holds a list of handlers, |
6555 | 2142 together with regular expressions that determine when to apply each |
2143 handler. Each element has this form: | |
2144 | |
2145 @example | |
2146 (@var{regexp} . @var{handler}) | |
2147 @end example | |
2148 | |
2149 @noindent | |
2150 All the Emacs primitives for file access and file name transformation | |
2151 check the given file name against @code{file-name-handler-alist}. If | |
2152 the file name matches @var{regexp}, the primitives handle that file by | |
2153 calling @var{handler}. | |
2154 | |
2155 The first argument given to @var{handler} is the name of the primitive; | |
2156 the remaining arguments are the arguments that were passed to that | |
2157 operation. (The first of these arguments is typically the file name | |
2158 itself.) For example, if you do this: | |
2159 | |
2160 @example | |
2161 (file-exists-p @var{filename}) | |
2162 @end example | |
2163 | |
2164 @noindent | |
2165 and @var{filename} has handler @var{handler}, then @var{handler} is | |
2166 called like this: | |
2167 | |
2168 @example | |
2169 (funcall @var{handler} 'file-exists-p @var{filename}) | |
2170 @end example | |
2171 | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2172 Here are the operations that a magic file name handler gets to handle: |
6555 | 2173 |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2174 @ifinfo |
6555 | 2175 @noindent |
2176 @code{add-name-to-file}, @code{copy-file}, @code{delete-directory}, | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2177 @code{delete-file}, |
12226 | 2178 @code{diff-latest-backup-file}, |
6555 | 2179 @code{directory-file-name}, |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2180 @code{directory-files}, |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
2181 @code{dired-call-process}, |
6555 | 2182 @code{dired-compress-file}, @code{dired-uncache}, |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2183 @code{expand-file-name}, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2184 @code{file-accessible-directory-p},@* |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2185 @code{file-attributes}, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2186 @code{file-directory-p}, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2187 @code{file-executable-p}, @code{file-exists-p},@* |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2188 @code{file-local-copy}, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2189 @code{file-modes}, @code{file-name-all-completions},@* |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2190 @code{file-name-as-directory}, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2191 @code{file-name-completion}, |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
2192 @code{file-name-directory}, |
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
2193 @code{file-name-nondirectory}, |
6555 | 2194 @code{file-name-sans-versions}, @code{file-newer-than-file-p}, |
15765
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2195 @code{file-ownership-preserved-p}, |
11626
0b86aef0c387
Mention file-regular-p operation.
Richard M. Stallman <rms@gnu.org>
parents:
8364
diff
changeset
|
2196 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, |
12226 | 2197 @code{file-truename}, @code{file-writable-p}, |
15765
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2198 @code{find-backup-file-name}, |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2199 @code{get-file-buffer},@* |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2200 @code{insert-directory}, |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
2201 @code{insert-file-contents}, |
15765
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2202 @code{load}, @code{make-directory}, |
6555 | 2203 @code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes}, |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2204 @code{set-visited-file-modtime}, @code{shell-command},@* |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2205 @code{unhandled-file-name-directory}, |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
2206 @code{vc-registered}, |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2207 @code{verify-visited-file-modtime},@* |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2208 @code{write-region}. |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2209 @end ifinfo |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2210 @iftex |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2211 @noindent |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2212 @flushleft |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2213 @code{add-name-to-file}, @code{copy-file}, @code{delete-directory}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2214 @code{delete-file}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2215 @code{diff-latest-backup-file}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2216 @code{directory-file-name}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2217 @code{directory-files}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2218 @code{dired-call-process}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2219 @code{dired-compress-file}, @code{dired-uncache}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2220 @code{expand-file-name}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2221 @code{file-accessible-direc@discretionary{}{}{}tory-p}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2222 @code{file-attributes}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2223 @code{file-direct@discretionary{}{}{}ory-p}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2224 @code{file-executable-p}, @code{file-exists-p}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2225 @code{file-local-copy}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2226 @code{file-modes}, @code{file-name-all-completions}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2227 @code{file-name-as-directory}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2228 @code{file-name-completion}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2229 @code{file-name-directory}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2230 @code{file-name-nondirec@discretionary{}{}{}tory}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2231 @code{file-name-sans-versions}, @code{file-newer-than-file-p}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2232 @code{file-ownership-pre@discretionary{}{}{}served-p}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2233 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2234 @code{file-truename}, @code{file-writable-p}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2235 @code{find-backup-file-name}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2236 @code{get-file-buffer}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2237 @code{insert-directory}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2238 @code{insert-file-contents}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2239 @code{load}, @code{make-direc@discretionary{}{}{}tory}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2240 @code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2241 @code{set-visited-file-modtime}, @code{shell-command}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2242 @code{unhandled-file-name-directory}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2243 @code{vc-regis@discretionary{}{}{}tered}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2244 @code{verify-visited-file-modtime}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2245 @code{write-region}. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2246 @end flushleft |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2247 @end iftex |
6555 | 2248 |
8118
56b5ed321f8d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2249 Handlers for @code{insert-file-contents} typically need to clear the |
56b5ed321f8d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2250 buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the |
56b5ed321f8d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2251 @var{visit} argument is non-@code{nil}. This also has the effect of |
56b5ed321f8d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2252 unlocking the buffer if it is locked. |
56b5ed321f8d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2253 |
6555 | 2254 The handler function must handle all of the above operations, and |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2255 possibly others to be added in the future. It need not implement all |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2256 these operations itself---when it has nothing special to do for a |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2257 certain operation, it can reinvoke the primitive, to handle the |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2258 operation ``in the usual way''. It should always reinvoke the primitive |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2259 for an operation it does not recognize. Here's one way to do this: |
6555 | 2260 |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2261 @smallexample |
6555 | 2262 (defun my-file-handler (operation &rest args) |
2263 ;; @r{First check for the specific operations} | |
2264 ;; @r{that we have special handling for.} | |
2265 (cond ((eq operation 'insert-file-contents) @dots{}) | |
2266 ((eq operation 'write-region) @dots{}) | |
2267 @dots{} | |
2268 ;; @r{Handle any operation we don't know about.} | |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2269 (t (let ((inhibit-file-name-handlers |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2270 (cons 'my-file-handler |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2271 (and (eq inhibit-file-name-operation operation) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2272 inhibit-file-name-handlers))) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2273 (inhibit-file-name-operation operation)) |
6555 | 2274 (apply operation args))))) |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2275 @end smallexample |
6555 | 2276 |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2277 When a handler function decides to call the ordinary Emacs primitive for |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2278 the operation at hand, it needs to prevent the primitive from calling |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2279 the same handler once again, thus leading to an infinite recursion. The |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2280 example above shows how to do this, with the variables |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2281 @code{inhibit-file-name-handlers} and |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2282 @code{inhibit-file-name-operation}. Be careful to use them exactly as |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2283 shown above; the details are crucial for proper behavior in the case of |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2284 multiple handlers, and for operations that have two file names that may |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2285 each have handlers. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2286 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2287 @defvar inhibit-file-name-handlers |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2288 This variable holds a list of handlers whose use is presently inhibited |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2289 for a certain operation. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2290 @end defvar |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2291 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2292 @defvar inhibit-file-name-operation |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2293 The operation for which certain handlers are presently inhibited. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2294 @end defvar |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2295 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2296 @defun find-file-name-handler file operation |
6555 | 2297 This function returns the handler function for file name @var{file}, or |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2298 @code{nil} if there is none. The argument @var{operation} should be the |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2299 operation to be performed on the file---the value you will pass to the |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2300 handler as its first argument when you call it. The operation is needed |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2301 for comparison with @code{inhibit-file-name-operation}. |
6555 | 2302 @end defun |
2303 | |
2304 @defun file-local-copy filename | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2305 This function copies file @var{filename} to an ordinary non-magic file, |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2306 if it isn't one already. |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2307 |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2308 If @var{filename} specifies a magic file name, which programs |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2309 outside Emacs cannot directly read or write, this copies the contents to |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2310 an ordinary file and returns that file's name. |
6555 | 2311 |
2312 If @var{filename} is an ordinary file name, not magic, then this function | |
2313 does nothing and returns @code{nil}. | |
2314 @end defun | |
2315 | |
2316 @defun unhandled-file-name-directory filename | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2317 This function returns the name of a directory that is not magic. It |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2318 uses the directory part of @var{filename} if that is not magic. For a |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2319 magic file name, it invokes the file name handler, which therefore |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2320 decides what value to return. |
6555 | 2321 |
2322 This is useful for running a subprocess; every subprocess must have a | |
2323 non-magic directory to serve as its current directory, and this function | |
2324 is a good way to come up with one. | |
2325 @end defun | |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2326 |
12067 | 2327 @node Format Conversion |
2328 @section File Format Conversion | |
2329 | |
2330 @cindex file format conversion | |
2331 @cindex encoding file formats | |
2332 @cindex decoding file formats | |
2333 The variable @code{format-alist} defines a list of @dfn{file formats}, | |
12098 | 2334 which describe textual representations used in files for the data (text, |
12067 | 2335 text-properties, and possibly other information) in an Emacs buffer. |
12098 | 2336 Emacs performs format conversion if appropriate when reading and writing |
2337 files. | |
12067 | 2338 |
2339 @defvar format-alist | |
2340 This list contains one format definition for each defined file format. | |
2341 @end defvar | |
2342 | |
2343 @cindex format definition | |
2344 Each format definition is a list of this form: | |
2345 | |
2346 @example | |
2347 (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn}) | |
2348 @end example | |
2349 | |
2350 Here is what the elements in a format definition mean: | |
2351 | |
2352 @table @var | |
2353 @item name | |
2354 The name of this format. | |
2355 | |
2356 @item doc-string | |
2357 A documentation string for the format. | |
2358 | |
2359 @item regexp | |
2360 A regular expression which is used to recognize files represented in | |
2361 this format. | |
2362 | |
2363 @item from-fn | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2364 A shell command or function to decode data in this format (to convert |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2365 file data into the usual Emacs data representation). |
12067 | 2366 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2367 A shell command is represented as a string; Emacs runs the command as a |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2368 filter to perform the conversion. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2369 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2370 If @var{from-fn} is a function, it is called with two arguments, @var{begin} |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2371 and @var{end}, which specify the part of the buffer it should convert. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2372 It should convert the text by editing it in place. Since this can |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2373 change the length of the text, @var{from-fn} should return the modified |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2374 end position. |
12067 | 2375 |
12098 | 2376 One responsibility of @var{from-fn} is to make sure that the beginning |
12067 | 2377 of the file no longer matches @var{regexp}. Otherwise it is likely to |
2378 get called again. | |
2379 | |
2380 @item to-fn | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2381 A shell command or function to encode data in this format---that is, to |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2382 convert the usual Emacs data representation into this format. |
12067 | 2383 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2384 If @var{to-fn} is a string, it is a shell command; Emacs runs the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2385 command as a filter to perform the conversion. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2386 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2387 If @var{to-fn} is a function, it is called with two arguments, @var{begin} |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2388 and @var{end}, which specify the part of the buffer it should convert. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2389 There are two ways it can do the conversion: |
12067 | 2390 |
2391 @itemize @bullet | |
2392 @item | |
2393 By editing the buffer in place. In this case, @var{to-fn} should | |
2394 return the end-position of the range of text, as modified. | |
2395 | |
2396 @item | |
2397 By returning a list of annotations. This is a list of elements of the | |
2398 form @code{(@var{position} . @var{string})}, where @var{position} is an | |
2399 integer specifying the relative position in the text to be written, and | |
2400 @var{string} is the annotation to add there. The list must be sorted in | |
2401 order of position when @var{to-fn} returns it. | |
2402 | |
2403 When @code{write-region} actually writes the text from the buffer to the | |
2404 file, it intermixes the specified annotations at the corresponding | |
2405 positions. All this takes place without modifying the buffer. | |
2406 @end itemize | |
2407 | |
2408 @item modify | |
2409 A flag, @code{t} if the encoding function modifies the buffer, and | |
2410 @code{nil} if it works by returning a list of annotations. | |
2411 | |
2412 @item mode | |
2413 A mode function to call after visiting a file converted from this | |
2414 format. | |
2415 @end table | |
2416 | |
2417 The function @code{insert-file-contents} automatically recognizes file | |
2418 formats when it reads the specified file. It checks the text of the | |
2419 beginning of the file against the regular expressions of the format | |
2420 definitions, and if it finds a match, it calls the decoding function for | |
2421 that format. Then it checks all the known formats over again. | |
2422 It keeps checking them until none of them is applicable. | |
2423 | |
2424 Visiting a file, with @code{find-file-noselect} or the commands that use | |
2425 it, performs conversion likewise (because it calls | |
12098 | 2426 @code{insert-file-contents}); it also calls the mode function for each |
2427 format that it decodes. It stores a list of the format names in the | |
2428 buffer-local variable @code{buffer-file-format}. | |
12067 | 2429 |
2430 @defvar buffer-file-format | |
12098 | 2431 This variable states the format of the visited file. More precisely, |
2432 this is a list of the file format names that were decoded in the course | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2433 of visiting the current buffer's file. It is always buffer-local in all |
12067 | 2434 buffers. |
2435 @end defvar | |
2436 | |
2437 When @code{write-region} writes data into a file, it first calls the | |
12098 | 2438 encoding functions for the formats listed in @code{buffer-file-format}, |
2439 in the order of appearance in the list. | |
12067 | 2440 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2441 @deffn Command format-write-file file format |
12067 | 2442 This command writes the current buffer contents into the file @var{file} |
2443 in format @var{format}, and makes that format the default for future | |
12098 | 2444 saves of the buffer. The argument @var{format} is a list of format |
2445 names. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2446 @end deffn |
12067 | 2447 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2448 @deffn Command format-find-file file format |
12226 | 2449 This command finds the file @var{file}, converting it according to |
2450 format @var{format}. It also makes @var{format} the default if the | |
2451 buffer is saved later. | |
2452 | |
2453 The argument @var{format} is a list of format names. If @var{format} is | |
2454 @code{nil}, no conversion takes place. Interactively, typing just | |
2455 @key{RET} for @var{format} specifies @code{nil}. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2456 @end deffn |
12226 | 2457 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2458 @deffn Command format-insert-file file format &optional beg end |
12226 | 2459 This command inserts the contents of file @var{file}, converting it |
2460 according to format @var{format}. If @var{beg} and @var{end} are | |
2461 non-@code{nil}, they specify which part of the file to read, as in | |
2462 @code{insert-file-contents} (@pxref{Reading from Files}). | |
2463 | |
2464 The return value is like what @code{insert-file-contents} returns: a | |
2465 list of the absolute file name and the length of the data inserted | |
2466 (after conversion). | |
2467 | |
2468 The argument @var{format} is a list of format names. If @var{format} is | |
2469 @code{nil}, no conversion takes place. Interactively, typing just | |
2470 @key{RET} for @var{format} specifies @code{nil}. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2471 @end deffn |
12226 | 2472 |
12067 | 2473 @defvar auto-save-file-format |
2474 This variable specifies the format to use for auto-saving. Its value is | |
2475 a list of format names, just like the value of | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2476 @code{buffer-file-format}; however, it is used instead of |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2477 @code{buffer-file-format} for writing auto-save files. This variable is |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2478 always buffer-local in all buffers. |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2479 @end defvar |