84067
|
1 @c -*-texinfo-*-
|
|
2 @c This is part of the GNU Emacs Lisp Reference Manual.
|
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
|
|
4 @c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
|
|
5 @c See the file elisp.texi for copying conditions.
|
|
6 @setfilename ../info/files
|
|
7 @node Files, Backups and Auto-Saving, Documentation, Top
|
|
8 @comment node-name, next, previous, up
|
|
9 @chapter Files
|
|
10
|
|
11 In Emacs, you can find, create, view, save, and otherwise work with
|
|
12 files and file directories. This chapter describes most of the
|
|
13 file-related functions of Emacs Lisp, but a few others are described in
|
|
14 @ref{Buffers}, and those related to backups and auto-saving are
|
|
15 described in @ref{Backups and Auto-Saving}.
|
|
16
|
|
17 Many of the file functions take one or more arguments that are file
|
|
18 names. A file name is actually a string. Most of these functions
|
|
19 expand file name arguments by calling @code{expand-file-name}, so that
|
|
20 @file{~} is handled correctly, as are relative file names (including
|
|
21 @samp{../}). These functions don't recognize environment variable
|
|
22 substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
|
|
23
|
|
24 When file I/O functions signal Lisp errors, they usually use the
|
|
25 condition @code{file-error} (@pxref{Handling Errors}). The error
|
|
26 message is in most cases obtained from the operating system, according
|
|
27 to locale @code{system-message-locale}, and decoded using coding system
|
|
28 @code{locale-coding-system} (@pxref{Locales}).
|
|
29
|
|
30 @menu
|
|
31 * Visiting Files:: Reading files into Emacs buffers for editing.
|
|
32 * Saving Buffers:: Writing changed buffers back into files.
|
|
33 * Reading from Files:: Reading files into buffers without visiting.
|
|
34 * Writing to Files:: Writing new files from parts of buffers.
|
|
35 * File Locks:: Locking and unlocking files, to prevent
|
|
36 simultaneous editing by two people.
|
|
37 * Information about Files:: Testing existence, accessibility, size of files.
|
|
38 * Changing Files:: Renaming files, changing protection, etc.
|
|
39 * File Names:: Decomposing and expanding file names.
|
|
40 * Contents of Directories:: Getting a list of the files in a directory.
|
|
41 * Create/Delete Dirs:: Creating and Deleting Directories.
|
|
42 * Magic File Names:: Defining "magic" special handling
|
|
43 for certain file names.
|
|
44 * Format Conversion:: Conversion to and from various file formats.
|
|
45 @end menu
|
|
46
|
|
47 @node Visiting Files
|
|
48 @section Visiting Files
|
|
49 @cindex finding files
|
|
50 @cindex visiting files
|
|
51
|
|
52 Visiting a file means reading a file into a buffer. Once this is
|
|
53 done, we say that the buffer is @dfn{visiting} that file, and call the
|
|
54 file ``the visited file'' of the buffer.
|
|
55
|
|
56 A file and a buffer are two different things. A file is information
|
|
57 recorded permanently in the computer (unless you delete it). A buffer,
|
|
58 on the other hand, is information inside of Emacs that will vanish at
|
|
59 the end of the editing session (or when you kill the buffer). Usually,
|
|
60 a buffer contains information that you have copied from a file; then we
|
|
61 say the buffer is visiting that file. The copy in the buffer is what
|
|
62 you modify with editing commands. Such changes to the buffer do not
|
|
63 change the file; therefore, to make the changes permanent, you must
|
|
64 @dfn{save} the buffer, which means copying the altered buffer contents
|
|
65 back into the file.
|
|
66
|
|
67 In spite of the distinction between files and buffers, people often
|
|
68 refer to a file when they mean a buffer and vice-versa. Indeed, we say,
|
|
69 ``I am editing a file,'' rather than, ``I am editing a buffer that I
|
|
70 will soon save as a file of the same name.'' Humans do not usually need
|
|
71 to make the distinction explicit. When dealing with a computer program,
|
|
72 however, it is good to keep the distinction in mind.
|
|
73
|
|
74 @menu
|
|
75 * Visiting Functions:: The usual interface functions for visiting.
|
|
76 * Subroutines of Visiting:: Lower-level subroutines that they use.
|
|
77 @end menu
|
|
78
|
|
79 @node Visiting Functions
|
|
80 @subsection Functions for Visiting Files
|
|
81
|
|
82 This section describes the functions normally used to visit files.
|
|
83 For historical reasons, these functions have names starting with
|
|
84 @samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for
|
|
85 functions and variables that access the visited file name of a buffer or
|
|
86 that find an existing buffer by its visited file name.
|
|
87
|
|
88 In a Lisp program, if you want to look at the contents of a file but
|
|
89 not alter it, the fastest way is to use @code{insert-file-contents} in a
|
|
90 temporary buffer. Visiting the file is not necessary and takes longer.
|
|
91 @xref{Reading from Files}.
|
|
92
|
|
93 @deffn Command find-file filename &optional wildcards
|
|
94 This command selects a buffer visiting the file @var{filename},
|
|
95 using an existing buffer if there is one, and otherwise creating a
|
|
96 new buffer and reading the file into it. It also returns that buffer.
|
|
97
|
|
98 Aside from some technical details, the body of the @code{find-file}
|
|
99 function is basically equivalent to:
|
|
100
|
|
101 @smallexample
|
|
102 (switch-to-buffer (find-file-noselect filename nil nil wildcards))
|
|
103 @end smallexample
|
|
104
|
|
105 @noindent
|
|
106 (See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
|
|
107
|
|
108 If @var{wildcards} is non-@code{nil}, which is always true in an
|
|
109 interactive call, then @code{find-file} expands wildcard characters in
|
|
110 @var{filename} and visits all the matching files.
|
|
111
|
|
112 When @code{find-file} is called interactively, it prompts for
|
|
113 @var{filename} in the minibuffer.
|
|
114 @end deffn
|
|
115
|
|
116 @defun find-file-noselect filename &optional nowarn rawfile wildcards
|
|
117 This function is the guts of all the file-visiting functions. It
|
|
118 returns a buffer visiting the file @var{filename}. You may make the
|
|
119 buffer current or display it in a window if you wish, but this
|
|
120 function does not do so.
|
|
121
|
|
122 The function returns an existing buffer if there is one; otherwise it
|
|
123 creates a new buffer and reads the file into it. When
|
|
124 @code{find-file-noselect} uses an existing buffer, it first verifies
|
|
125 that the file has not changed since it was last visited or saved in
|
|
126 that buffer. If the file has changed, this function asks the user
|
|
127 whether to reread the changed file. If the user says @samp{yes}, any
|
|
128 edits previously made in the buffer are lost.
|
|
129
|
|
130 Reading the file involves decoding the file's contents (@pxref{Coding
|
|
131 Systems}), including end-of-line conversion, and format conversion
|
|
132 (@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil},
|
|
133 then @code{find-file-noselect} expands wildcard characters in
|
|
134 @var{filename} and visits all the matching files.
|
|
135
|
|
136 This function displays warning or advisory messages in various peculiar
|
|
137 cases, unless the optional argument @var{nowarn} is non-@code{nil}. For
|
|
138 example, if it needs to create a buffer, and there is no file named
|
|
139 @var{filename}, it displays the message @samp{(New file)} in the echo
|
|
140 area, and leaves the buffer empty.
|
|
141
|
|
142 The @code{find-file-noselect} function normally calls
|
|
143 @code{after-find-file} after reading the file (@pxref{Subroutines of
|
|
144 Visiting}). That function sets the buffer major mode, parses local
|
|
145 variables, warns the user if there exists an auto-save file more recent
|
|
146 than the file just visited, and finishes by running the functions in
|
|
147 @code{find-file-hook}.
|
|
148
|
|
149 If the optional argument @var{rawfile} is non-@code{nil}, then
|
|
150 @code{after-find-file} is not called, and the
|
|
151 @code{find-file-not-found-functions} are not run in case of failure.
|
|
152 What's more, a non-@code{nil} @var{rawfile} value suppresses coding
|
|
153 system conversion and format conversion.
|
|
154
|
|
155 The @code{find-file-noselect} function usually returns the buffer that
|
|
156 is visiting the file @var{filename}. But, if wildcards are actually
|
|
157 used and expanded, it returns a list of buffers that are visiting the
|
|
158 various files.
|
|
159
|
|
160 @example
|
|
161 @group
|
|
162 (find-file-noselect "/etc/fstab")
|
|
163 @result{} #<buffer fstab>
|
|
164 @end group
|
|
165 @end example
|
|
166 @end defun
|
|
167
|
|
168 @deffn Command find-file-other-window filename &optional wildcards
|
|
169 This command selects a buffer visiting the file @var{filename}, but
|
|
170 does so in a window other than the selected window. It may use another
|
|
171 existing window or split a window; see @ref{Displaying Buffers}.
|
|
172
|
|
173 When this command is called interactively, it prompts for
|
|
174 @var{filename}.
|
|
175 @end deffn
|
|
176
|
|
177 @deffn Command find-file-read-only filename &optional wildcards
|
|
178 This command selects a buffer visiting the file @var{filename}, like
|
|
179 @code{find-file}, but it marks the buffer as read-only. @xref{Read Only
|
|
180 Buffers}, for related functions and variables.
|
|
181
|
|
182 When this command is called interactively, it prompts for
|
|
183 @var{filename}.
|
|
184 @end deffn
|
|
185
|
|
186 @deffn Command view-file filename
|
|
187 This command visits @var{filename} using View mode, returning to the
|
|
188 previous buffer when you exit View mode. View mode is a minor mode that
|
|
189 provides commands to skim rapidly through the file, but does not let you
|
|
190 modify the text. Entering View mode runs the normal hook
|
|
191 @code{view-mode-hook}. @xref{Hooks}.
|
|
192
|
|
193 When @code{view-file} is called interactively, it prompts for
|
|
194 @var{filename}.
|
|
195 @end deffn
|
|
196
|
|
197 @defopt find-file-wildcards
|
|
198 If this variable is non-@code{nil}, then the various @code{find-file}
|
|
199 commands check for wildcard characters and visit all the files that
|
|
200 match them (when invoked interactively or when their @var{wildcards}
|
|
201 argument is non-@code{nil}). If this option is @code{nil}, then
|
|
202 the @code{find-file} commands ignore their @var{wildcards} argument
|
|
203 and never treat wildcard characters specially.
|
|
204 @end defopt
|
|
205
|
|
206 @defvar find-file-hook
|
|
207 The value of this variable is a list of functions to be called after a
|
|
208 file is visited. The file's local-variables specification (if any) will
|
|
209 have been processed before the hooks are run. The buffer visiting the
|
|
210 file is current when the hook functions are run.
|
|
211
|
|
212 This variable is a normal hook. @xref{Hooks}.
|
|
213 @end defvar
|
|
214
|
|
215 @defvar find-file-not-found-functions
|
|
216 The value of this variable is a list of functions to be called when
|
|
217 @code{find-file} or @code{find-file-noselect} is passed a nonexistent
|
|
218 file name. @code{find-file-noselect} calls these functions as soon as
|
|
219 it detects a nonexistent file. It calls them in the order of the list,
|
|
220 until one of them returns non-@code{nil}. @code{buffer-file-name} is
|
|
221 already set up.
|
|
222
|
|
223 This is not a normal hook because the values of the functions are
|
|
224 used, and in many cases only some of the functions are called.
|
|
225 @end defvar
|
|
226
|
|
227 @node Subroutines of Visiting
|
|
228 @comment node-name, next, previous, up
|
|
229 @subsection Subroutines of Visiting
|
|
230
|
|
231 The @code{find-file-noselect} function uses two important subroutines
|
|
232 which are sometimes useful in user Lisp code: @code{create-file-buffer}
|
|
233 and @code{after-find-file}. This section explains how to use them.
|
|
234
|
|
235 @defun create-file-buffer filename
|
|
236 This function creates a suitably named buffer for visiting
|
|
237 @var{filename}, and returns it. It uses @var{filename} (sans directory)
|
|
238 as the name if that name is free; otherwise, it appends a string such as
|
|
239 @samp{<2>} to get an unused name. See also @ref{Creating Buffers}.
|
|
240
|
|
241 @strong{Please note:} @code{create-file-buffer} does @emph{not}
|
|
242 associate the new buffer with a file and does not select the buffer.
|
|
243 It also does not use the default major mode.
|
|
244
|
|
245 @example
|
|
246 @group
|
|
247 (create-file-buffer "foo")
|
|
248 @result{} #<buffer foo>
|
|
249 @end group
|
|
250 @group
|
|
251 (create-file-buffer "foo")
|
|
252 @result{} #<buffer foo<2>>
|
|
253 @end group
|
|
254 @group
|
|
255 (create-file-buffer "foo")
|
|
256 @result{} #<buffer foo<3>>
|
|
257 @end group
|
|
258 @end example
|
|
259
|
|
260 This function is used by @code{find-file-noselect}.
|
|
261 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
|
|
262 @end defun
|
|
263
|
|
264 @defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
|
|
265 This function sets the buffer major mode, and parses local variables
|
|
266 (@pxref{Auto Major Mode}). It is called by @code{find-file-noselect}
|
|
267 and by the default revert function (@pxref{Reverting}).
|
|
268
|
|
269 @cindex new file message
|
|
270 @cindex file open error
|
|
271 If reading the file got an error because the file does not exist, but
|
|
272 its directory does exist, the caller should pass a non-@code{nil} value
|
|
273 for @var{error}. In that case, @code{after-find-file} issues a warning:
|
|
274 @samp{(New file)}. For more serious errors, the caller should usually not
|
|
275 call @code{after-find-file}.
|
|
276
|
|
277 If @var{warn} is non-@code{nil}, then this function issues a warning
|
|
278 if an auto-save file exists and is more recent than the visited file.
|
|
279
|
|
280 If @var{noauto} is non-@code{nil}, that says not to enable or disable
|
|
281 Auto-Save mode. The mode remains enabled if it was enabled before.
|
|
282
|
|
283 If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
|
|
284 means this call was from @code{revert-buffer}. This has no direct
|
|
285 effect, but some mode functions and hook functions check the value
|
|
286 of this variable.
|
|
287
|
|
288 If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
|
|
289 major mode, don't process local variables specifications in the file,
|
|
290 and don't run @code{find-file-hook}. This feature is used by
|
|
291 @code{revert-buffer} in some cases.
|
|
292
|
|
293 The last thing @code{after-find-file} does is call all the functions
|
|
294 in the list @code{find-file-hook}.
|
|
295 @end defun
|
|
296
|
|
297 @node Saving Buffers
|
|
298 @section Saving Buffers
|
|
299 @cindex saving buffers
|
|
300
|
|
301 When you edit a file in Emacs, you are actually working on a buffer
|
|
302 that is visiting that file---that is, the contents of the file are
|
|
303 copied into the buffer and the copy is what you edit. Changes to the
|
|
304 buffer do not change the file until you @dfn{save} the buffer, which
|
|
305 means copying the contents of the buffer into the file.
|
|
306
|
|
307 @deffn Command save-buffer &optional backup-option
|
|
308 This function saves the contents of the current buffer in its visited
|
|
309 file if the buffer has been modified since it was last visited or saved.
|
|
310 Otherwise it does nothing.
|
|
311
|
|
312 @code{save-buffer} is responsible for making backup files. Normally,
|
|
313 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
|
|
314 file only if this is the first save since visiting the file. Other
|
|
315 values for @var{backup-option} request the making of backup files in
|
|
316 other circumstances:
|
|
317
|
|
318 @itemize @bullet
|
|
319 @item
|
|
320 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
|
|
321 @code{save-buffer} function marks this version of the file to be
|
|
322 backed up when the buffer is next saved.
|
|
323
|
|
324 @item
|
|
325 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
|
|
326 @code{save-buffer} function unconditionally backs up the previous
|
|
327 version of the file before saving it.
|
|
328
|
|
329 @item
|
|
330 With an argument of 0, unconditionally do @emph{not} make any backup file.
|
|
331 @end itemize
|
|
332 @end deffn
|
|
333
|
|
334 @deffn Command save-some-buffers &optional save-silently-p pred
|
|
335 @anchor{Definition of save-some-buffers}
|
|
336 This command saves some modified file-visiting buffers. Normally it
|
|
337 asks the user about each buffer. But if @var{save-silently-p} is
|
|
338 non-@code{nil}, it saves all the file-visiting buffers without querying
|
|
339 the user.
|
|
340
|
|
341 The optional @var{pred} argument controls which buffers to ask about
|
|
342 (or to save silently if @var{save-silently-p} is non-@code{nil}).
|
|
343 If it is @code{nil}, that means to ask only about file-visiting buffers.
|
|
344 If it is @code{t}, that means also offer to save certain other non-file
|
|
345 buffers---those that have a non-@code{nil} buffer-local value of
|
|
346 @code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says
|
|
347 @samp{yes} to saving a non-file buffer is asked to specify the file
|
|
348 name to use. The @code{save-buffers-kill-emacs} function passes the
|
|
349 value @code{t} for @var{pred}.
|
|
350
|
|
351 If @var{pred} is neither @code{t} nor @code{nil}, then it should be
|
|
352 a function of no arguments. It will be called in each buffer to decide
|
|
353 whether to offer to save that buffer. If it returns a non-@code{nil}
|
|
354 value in a certain buffer, that means do offer to save that buffer.
|
|
355 @end deffn
|
|
356
|
|
357 @deffn Command write-file filename &optional confirm
|
|
358 @anchor{Definition of write-file}
|
|
359 This function writes the current buffer into file @var{filename}, makes
|
|
360 the buffer visit that file, and marks it not modified. Then it renames
|
|
361 the buffer based on @var{filename}, appending a string like @samp{<2>}
|
|
362 if necessary to make a unique buffer name. It does most of this work by
|
|
363 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
|
|
364 @code{save-buffer}.
|
|
365
|
|
366 If @var{confirm} is non-@code{nil}, that means to ask for confirmation
|
|
367 before overwriting an existing file. Interactively, confirmation is
|
|
368 required, unless the user supplies a prefix argument.
|
|
369
|
|
370 If @var{filename} is an existing directory, or a symbolic link to one,
|
|
371 @code{write-file} uses the name of the visited file, in directory
|
|
372 @var{filename}. If the buffer is not visiting a file, it uses the
|
|
373 buffer name instead.
|
|
374 @end deffn
|
|
375
|
|
376 Saving a buffer runs several hooks. It also performs format
|
|
377 conversion (@pxref{Format Conversion}).
|
|
378
|
|
379 @defvar write-file-functions
|
|
380 The value of this variable is a list of functions to be called before
|
|
381 writing out a buffer to its visited file. If one of them returns
|
|
382 non-@code{nil}, the file is considered already written and the rest of
|
|
383 the functions are not called, nor is the usual code for writing the file
|
|
384 executed.
|
|
385
|
|
386 If a function in @code{write-file-functions} returns non-@code{nil}, it
|
|
387 is responsible for making a backup file (if that is appropriate).
|
|
388 To do so, execute the following code:
|
|
389
|
|
390 @example
|
|
391 (or buffer-backed-up (backup-buffer))
|
|
392 @end example
|
|
393
|
|
394 You might wish to save the file modes value returned by
|
|
395 @code{backup-buffer} and use that (if non-@code{nil}) to set the mode
|
|
396 bits of the file that you write. This is what @code{save-buffer}
|
|
397 normally does. @xref{Making Backups,, Making Backup Files}.
|
|
398
|
|
399 The hook functions in @code{write-file-functions} are also responsible
|
|
400 for encoding the data (if desired): they must choose a suitable coding
|
|
401 system and end-of-line conversion (@pxref{Lisp and Coding Systems}),
|
|
402 perform the encoding (@pxref{Explicit Encoding}), and set
|
|
403 @code{last-coding-system-used} to the coding system that was used
|
|
404 (@pxref{Encoding and I/O}).
|
|
405
|
|
406 If you set this hook locally in a buffer, it is assumed to be
|
|
407 associated with the file or the way the contents of the buffer were
|
|
408 obtained. Thus the variable is marked as a permanent local, so that
|
|
409 changing the major mode does not alter a buffer-local value. On the
|
|
410 other hand, calling @code{set-visited-file-name} will reset it.
|
|
411 If this is not what you want, you might like to use
|
|
412 @code{write-contents-functions} instead.
|
|
413
|
|
414 Even though this is not a normal hook, you can use @code{add-hook} and
|
|
415 @code{remove-hook} to manipulate the list. @xref{Hooks}.
|
|
416 @end defvar
|
|
417
|
|
418 @c Emacs 19 feature
|
|
419 @defvar write-contents-functions
|
|
420 This works just like @code{write-file-functions}, but it is intended
|
|
421 for hooks that pertain to the buffer's contents, not to the particular
|
|
422 visited file or its location. Such hooks are usually set up by major
|
|
423 modes, as buffer-local bindings for this variable. This variable
|
|
424 automatically becomes buffer-local whenever it is set; switching to a
|
|
425 new major mode always resets this variable, but calling
|
|
426 @code{set-visited-file-name} does not.
|
|
427
|
|
428 If any of the functions in this hook returns non-@code{nil}, the file
|
|
429 is considered already written and the rest are not called and neither
|
|
430 are the functions in @code{write-file-functions}.
|
|
431 @end defvar
|
|
432
|
|
433 @defopt before-save-hook
|
|
434 This normal hook runs before a buffer is saved in its visited file,
|
|
435 regardless of whether that is done normally or by one of the hooks
|
|
436 described above. For instance, the @file{copyright.el} program uses
|
|
437 this hook to make sure the file you are saving has the current year in
|
|
438 its copyright notice.
|
|
439 @end defopt
|
|
440
|
|
441 @c Emacs 19 feature
|
|
442 @defopt after-save-hook
|
|
443 This normal hook runs after a buffer has been saved in its visited file.
|
|
444 One use of this hook is in Fast Lock mode; it uses this hook to save the
|
|
445 highlighting information in a cache file.
|
|
446 @end defopt
|
|
447
|
|
448 @defopt file-precious-flag
|
|
449 If this variable is non-@code{nil}, then @code{save-buffer} protects
|
|
450 against I/O errors while saving by writing the new file to a temporary
|
|
451 name instead of the name it is supposed to have, and then renaming it to
|
|
452 the intended name after it is clear there are no errors. This procedure
|
|
453 prevents problems such as a lack of disk space from resulting in an
|
|
454 invalid file.
|
|
455
|
|
456 As a side effect, backups are necessarily made by copying. @xref{Rename
|
|
457 or Copy}. Yet, at the same time, saving a precious file always breaks
|
|
458 all hard links between the file you save and other file names.
|
|
459
|
|
460 Some modes give this variable a non-@code{nil} buffer-local value
|
|
461 in particular buffers.
|
|
462 @end defopt
|
|
463
|
|
464 @defopt require-final-newline
|
|
465 This variable determines whether files may be written out that do
|
|
466 @emph{not} end with a newline. If the value of the variable is
|
|
467 @code{t}, then @code{save-buffer} silently adds a newline at the end of
|
|
468 the file whenever the buffer being saved does not already end in one.
|
|
469 If the value of the variable is non-@code{nil}, but not @code{t}, then
|
|
470 @code{save-buffer} asks the user whether to add a newline each time the
|
|
471 case arises.
|
|
472
|
|
473 If the value of the variable is @code{nil}, then @code{save-buffer}
|
|
474 doesn't add newlines at all. @code{nil} is the default value, but a few
|
|
475 major modes set it to @code{t} in particular buffers.
|
|
476 @end defopt
|
|
477
|
|
478 See also the function @code{set-visited-file-name} (@pxref{Buffer File
|
|
479 Name}).
|
|
480
|
|
481 @node Reading from Files
|
|
482 @comment node-name, next, previous, up
|
|
483 @section Reading from Files
|
|
484 @cindex reading from files
|
|
485
|
|
486 You can copy a file from the disk and insert it into a buffer
|
|
487 using the @code{insert-file-contents} function. Don't use the user-level
|
|
488 command @code{insert-file} in a Lisp program, as that sets the mark.
|
|
489
|
|
490 @defun insert-file-contents filename &optional visit beg end replace
|
|
491 This function inserts the contents of file @var{filename} into the
|
|
492 current buffer after point. It returns a list of the absolute file name
|
|
493 and the length of the data inserted. An error is signaled if
|
|
494 @var{filename} is not the name of a file that can be read.
|
|
495
|
|
496 The function @code{insert-file-contents} checks the file contents
|
|
497 against the defined file formats, and converts the file contents if
|
|
498 appropriate and also calls the functions in
|
|
499 the list @code{after-insert-file-functions}. @xref{Format Conversion}.
|
|
500 Normally, one of the functions in the
|
|
501 @code{after-insert-file-functions} list determines the coding system
|
|
502 (@pxref{Coding Systems}) used for decoding the file's contents,
|
|
503 including end-of-line conversion.
|
|
504
|
|
505 If @var{visit} is non-@code{nil}, this function additionally marks the
|
|
506 buffer as unmodified and sets up various fields in the buffer so that it
|
|
507 is visiting the file @var{filename}: these include the buffer's visited
|
|
508 file name and its last save file modtime. This feature is used by
|
|
509 @code{find-file-noselect} and you probably should not use it yourself.
|
|
510
|
|
511 If @var{beg} and @var{end} are non-@code{nil}, they should be integers
|
|
512 specifying the portion of the file to insert. In this case, @var{visit}
|
|
513 must be @code{nil}. For example,
|
|
514
|
|
515 @example
|
|
516 (insert-file-contents filename nil 0 500)
|
|
517 @end example
|
|
518
|
|
519 @noindent
|
|
520 inserts the first 500 characters of a file.
|
|
521
|
|
522 If the argument @var{replace} is non-@code{nil}, it means to replace the
|
|
523 contents of the buffer (actually, just the accessible portion) with the
|
|
524 contents of the file. This is better than simply deleting the buffer
|
|
525 contents and inserting the whole file, because (1) it preserves some
|
|
526 marker positions and (2) it puts less data in the undo list.
|
|
527
|
|
528 It is possible to read a special file (such as a FIFO or an I/O device)
|
|
529 with @code{insert-file-contents}, as long as @var{replace} and
|
|
530 @var{visit} are @code{nil}.
|
|
531 @end defun
|
|
532
|
|
533 @defun insert-file-contents-literally filename &optional visit beg end replace
|
|
534 This function works like @code{insert-file-contents} except that it does
|
|
535 not do format decoding (@pxref{Format Conversion}), does not do
|
|
536 character code conversion (@pxref{Coding Systems}), does not run
|
|
537 @code{find-file-hook}, does not perform automatic uncompression, and so
|
|
538 on.
|
|
539 @end defun
|
|
540
|
|
541 If you want to pass a file name to another process so that another
|
|
542 program can read the file, use the function @code{file-local-copy}; see
|
|
543 @ref{Magic File Names}.
|
|
544
|
|
545 @node Writing to Files
|
|
546 @comment node-name, next, previous, up
|
|
547 @section Writing to Files
|
|
548 @cindex writing to files
|
|
549
|
|
550 You can write the contents of a buffer, or part of a buffer, directly
|
|
551 to a file on disk using the @code{append-to-file} and
|
|
552 @code{write-region} functions. Don't use these functions to write to
|
|
553 files that are being visited; that could cause confusion in the
|
|
554 mechanisms for visiting.
|
|
555
|
|
556 @deffn Command append-to-file start end filename
|
|
557 This function appends the contents of the region delimited by
|
|
558 @var{start} and @var{end} in the current buffer to the end of file
|
|
559 @var{filename}. If that file does not exist, it is created. This
|
|
560 function returns @code{nil}.
|
|
561
|
|
562 An error is signaled if @var{filename} specifies a nonwritable file,
|
|
563 or a nonexistent file in a directory where files cannot be created.
|
|
564
|
|
565 When called from Lisp, this function is completely equivalent to:
|
|
566
|
|
567 @example
|
|
568 (write-region start end filename t)
|
|
569 @end example
|
|
570 @end deffn
|
|
571
|
|
572 @deffn Command write-region start end filename &optional append visit lockname mustbenew
|
|
573 This function writes the region delimited by @var{start} and @var{end}
|
|
574 in the current buffer into the file specified by @var{filename}.
|
|
575
|
|
576 If @var{start} is @code{nil}, then the command writes the entire buffer
|
|
577 contents (@emph{not} just the accessible portion) to the file and
|
|
578 ignores @var{end}.
|
|
579
|
|
580 @c Emacs 19 feature
|
|
581 If @var{start} is a string, then @code{write-region} writes or appends
|
|
582 that string, rather than text from the buffer. @var{end} is ignored in
|
|
583 this case.
|
|
584
|
|
585 If @var{append} is non-@code{nil}, then the specified text is appended
|
|
586 to the existing file contents (if any). If @var{append} is an
|
|
587 integer, @code{write-region} seeks to that byte offset from the start
|
|
588 of the file and writes the data from there.
|
|
589
|
|
590 If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
|
|
591 for confirmation if @var{filename} names an existing file. If
|
|
592 @var{mustbenew} is the symbol @code{excl}, then @code{write-region}
|
|
593 does not ask for confirmation, but instead it signals an error
|
|
594 @code{file-already-exists} if the file already exists.
|
|
595
|
|
596 The test for an existing file, when @var{mustbenew} is @code{excl}, uses
|
|
597 a special system feature. At least for files on a local disk, there is
|
|
598 no chance that some other program could create a file of the same name
|
|
599 before Emacs does, without Emacs's noticing.
|
|
600
|
|
601 If @var{visit} is @code{t}, then Emacs establishes an association
|
|
602 between the buffer and the file: the buffer is then visiting that file.
|
|
603 It also sets the last file modification time for the current buffer to
|
|
604 @var{filename}'s modtime, and marks the buffer as not modified. This
|
|
605 feature is used by @code{save-buffer}, but you probably should not use
|
|
606 it yourself.
|
|
607
|
|
608 @c Emacs 19 feature
|
|
609 If @var{visit} is a string, it specifies the file name to visit. This
|
|
610 way, you can write the data to one file (@var{filename}) while recording
|
|
611 the buffer as visiting another file (@var{visit}). The argument
|
|
612 @var{visit} is used in the echo area message and also for file locking;
|
|
613 @var{visit} is stored in @code{buffer-file-name}. This feature is used
|
|
614 to implement @code{file-precious-flag}; don't use it yourself unless you
|
|
615 really know what you're doing.
|
|
616
|
|
617 The optional argument @var{lockname}, if non-@code{nil}, specifies the
|
|
618 file name to use for purposes of locking and unlocking, overriding
|
|
619 @var{filename} and @var{visit} for that purpose.
|
|
620
|
|
621 The function @code{write-region} converts the data which it writes to
|
|
622 the appropriate file formats specified by @code{buffer-file-format}
|
|
623 and also calls the functions in the list
|
|
624 @code{write-region-annotate-functions}.
|
|
625 @xref{Format Conversion}.
|
|
626
|
|
627 Normally, @code{write-region} displays the message @samp{Wrote
|
|
628 @var{filename}} in the echo area. If @var{visit} is neither @code{t}
|
|
629 nor @code{nil} nor a string, then this message is inhibited. This
|
|
630 feature is useful for programs that use files for internal purposes,
|
|
631 files that the user does not need to know about.
|
|
632 @end deffn
|
|
633
|
|
634 @defmac with-temp-file file body@dots{}
|
|
635 @anchor{Definition of with-temp-file}
|
|
636 The @code{with-temp-file} macro evaluates the @var{body} forms with a
|
|
637 temporary buffer as the current buffer; then, at the end, it writes the
|
|
638 buffer contents into file @var{file}. It kills the temporary buffer
|
|
639 when finished, restoring the buffer that was current before the
|
|
640 @code{with-temp-file} form. Then it returns the value of the last form
|
|
641 in @var{body}.
|
|
642
|
|
643 The current buffer is restored even in case of an abnormal exit via
|
|
644 @code{throw} or error (@pxref{Nonlocal Exits}).
|
|
645
|
|
646 See also @code{with-temp-buffer} in @ref{Definition of
|
|
647 with-temp-buffer,, The Current Buffer}.
|
|
648 @end defmac
|
|
649
|
|
650 @node File Locks
|
|
651 @section File Locks
|
|
652 @cindex file locks
|
|
653 @cindex lock file
|
|
654
|
|
655 When two users edit the same file at the same time, they are likely
|
|
656 to interfere with each other. Emacs tries to prevent this situation
|
|
657 from arising by recording a @dfn{file lock} when a file is being
|
|
658 modified. (File locks are not implemented on Microsoft systems.)
|
|
659 Emacs can then detect the first attempt to modify a buffer visiting a
|
|
660 file that is locked by another Emacs job, and ask the user what to do.
|
|
661 The file lock is really a file, a symbolic link with a special name,
|
|
662 stored in the same directory as the file you are editing.
|
|
663
|
|
664 When you access files using NFS, there may be a small probability that
|
|
665 you and another user will both lock the same file ``simultaneously.''
|
|
666 If this happens, it is possible for the two users to make changes
|
|
667 simultaneously, but Emacs will still warn the user who saves second.
|
|
668 Also, the detection of modification of a buffer visiting a file changed
|
|
669 on disk catches some cases of simultaneous editing; see
|
|
670 @ref{Modification Time}.
|
|
671
|
|
672 @defun file-locked-p filename
|
|
673 This function returns @code{nil} if the file @var{filename} is not
|
|
674 locked. It returns @code{t} if it is locked by this Emacs process, and
|
|
675 it returns the name of the user who has locked it if it is locked by
|
|
676 some other job.
|
|
677
|
|
678 @example
|
|
679 @group
|
|
680 (file-locked-p "foo")
|
|
681 @result{} nil
|
|
682 @end group
|
|
683 @end example
|
|
684 @end defun
|
|
685
|
|
686 @defun lock-buffer &optional filename
|
|
687 This function locks the file @var{filename}, if the current buffer is
|
|
688 modified. The argument @var{filename} defaults to the current buffer's
|
|
689 visited file. Nothing is done if the current buffer is not visiting a
|
|
690 file, or is not modified, or if the system does not support locking.
|
|
691 @end defun
|
|
692
|
|
693 @defun unlock-buffer
|
|
694 This function unlocks the file being visited in the current buffer,
|
|
695 if the buffer is modified. If the buffer is not modified, then
|
|
696 the file should not be locked, so this function does nothing. It also
|
|
697 does nothing if the current buffer is not visiting a file, or if the
|
|
698 system does not support locking.
|
|
699 @end defun
|
|
700
|
|
701 File locking is not supported on some systems. On systems that do not
|
|
702 support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
|
|
703 @code{file-locked-p} do nothing and return @code{nil}.
|
|
704
|
|
705 @defun ask-user-about-lock file other-user
|
|
706 This function is called when the user tries to modify @var{file}, but it
|
|
707 is locked by another user named @var{other-user}. The default
|
|
708 definition of this function asks the user to say what to do. The value
|
|
709 this function returns determines what Emacs does next:
|
|
710
|
|
711 @itemize @bullet
|
|
712 @item
|
|
713 A value of @code{t} says to grab the lock on the file. Then
|
|
714 this user may edit the file and @var{other-user} loses the lock.
|
|
715
|
|
716 @item
|
|
717 A value of @code{nil} says to ignore the lock and let this
|
|
718 user edit the file anyway.
|
|
719
|
|
720 @item
|
|
721 @kindex file-locked
|
|
722 This function may instead signal a @code{file-locked} error, in which
|
|
723 case the change that the user was about to make does not take place.
|
|
724
|
|
725 The error message for this error looks like this:
|
|
726
|
|
727 @example
|
|
728 @error{} File is locked: @var{file} @var{other-user}
|
|
729 @end example
|
|
730
|
|
731 @noindent
|
|
732 where @code{file} is the name of the file and @var{other-user} is the
|
|
733 name of the user who has locked the file.
|
|
734 @end itemize
|
|
735
|
|
736 If you wish, you can replace the @code{ask-user-about-lock} function
|
|
737 with your own version that makes the decision in another way. The code
|
|
738 for its usual definition is in @file{userlock.el}.
|
|
739 @end defun
|
|
740
|
|
741 @node Information about Files
|
|
742 @section Information about Files
|
|
743 @cindex file, information about
|
|
744
|
|
745 The functions described in this section all operate on strings that
|
|
746 designate file names. With a few exceptions, all the functions have
|
|
747 names that begin with the word @samp{file}. These functions all
|
|
748 return information about actual files or directories, so their
|
|
749 arguments must all exist as actual files or directories unless
|
|
750 otherwise noted.
|
|
751
|
|
752 @menu
|
|
753 * Testing Accessibility:: Is a given file readable? Writable?
|
|
754 * Kinds of Files:: Is it a directory? A symbolic link?
|
|
755 * Truenames:: Eliminating symbolic links from a file name.
|
|
756 * File Attributes:: How large is it? Any other names? Etc.
|
|
757 * Locating Files:: How to find a file in standard places.
|
|
758 @end menu
|
|
759
|
|
760 @node Testing Accessibility
|
|
761 @comment node-name, next, previous, up
|
|
762 @subsection Testing Accessibility
|
|
763 @cindex accessibility of a file
|
|
764 @cindex file accessibility
|
|
765
|
|
766 These functions test for permission to access a file in specific
|
|
767 ways. Unless explicitly stated otherwise, they recursively follow
|
|
768 symbolic links for their file name arguments, at all levels (at the
|
|
769 level of the file itself and at all levels of parent directories).
|
|
770
|
|
771 @defun file-exists-p filename
|
|
772 This function returns @code{t} if a file named @var{filename} appears
|
|
773 to exist. This does not mean you can necessarily read the file, only
|
|
774 that you can find out its attributes. (On Unix and GNU/Linux, this is
|
|
775 true if the file exists and you have execute permission on the
|
|
776 containing directories, regardless of the protection of the file
|
|
777 itself.)
|
|
778
|
|
779 If the file does not exist, or if fascist access control policies
|
|
780 prevent you from finding the attributes of the file, this function
|
|
781 returns @code{nil}.
|
|
782
|
|
783 Directories are files, so @code{file-exists-p} returns @code{t} when
|
|
784 given a directory name. However, symbolic links are treated
|
|
785 specially; @code{file-exists-p} returns @code{t} for a symbolic link
|
|
786 name only if the target file exists.
|
|
787 @end defun
|
|
788
|
|
789 @defun file-readable-p filename
|
|
790 This function returns @code{t} if a file named @var{filename} exists
|
|
791 and you can read it. It returns @code{nil} otherwise.
|
|
792
|
|
793 @example
|
|
794 @group
|
|
795 (file-readable-p "files.texi")
|
|
796 @result{} t
|
|
797 @end group
|
|
798 @group
|
|
799 (file-exists-p "/usr/spool/mqueue")
|
|
800 @result{} t
|
|
801 @end group
|
|
802 @group
|
|
803 (file-readable-p "/usr/spool/mqueue")
|
|
804 @result{} nil
|
|
805 @end group
|
|
806 @end example
|
|
807 @end defun
|
|
808
|
|
809 @c Emacs 19 feature
|
|
810 @defun file-executable-p filename
|
|
811 This function returns @code{t} if a file named @var{filename} exists and
|
|
812 you can execute it. It returns @code{nil} otherwise. On Unix and
|
|
813 GNU/Linux, if the file is a directory, execute permission means you can
|
|
814 check the existence and attributes of files inside the directory, and
|
|
815 open those files if their modes permit.
|
|
816 @end defun
|
|
817
|
|
818 @defun file-writable-p filename
|
|
819 This function returns @code{t} if the file @var{filename} can be written
|
|
820 or created by you, and @code{nil} otherwise. A file is writable if the
|
|
821 file exists and you can write it. It is creatable if it does not exist,
|
|
822 but the specified directory does exist and you can write in that
|
|
823 directory.
|
|
824
|
|
825 In the third example below, @file{foo} is not writable because the
|
|
826 parent directory does not exist, even though the user could create such
|
|
827 a directory.
|
|
828
|
|
829 @example
|
|
830 @group
|
|
831 (file-writable-p "~/foo")
|
|
832 @result{} t
|
|
833 @end group
|
|
834 @group
|
|
835 (file-writable-p "/foo")
|
|
836 @result{} nil
|
|
837 @end group
|
|
838 @group
|
|
839 (file-writable-p "~/no-such-dir/foo")
|
|
840 @result{} nil
|
|
841 @end group
|
|
842 @end example
|
|
843 @end defun
|
|
844
|
|
845 @c Emacs 19 feature
|
|
846 @defun file-accessible-directory-p dirname
|
|
847 This function returns @code{t} if you have permission to open existing
|
|
848 files in the directory whose name as a file is @var{dirname};
|
|
849 otherwise (or if there is no such directory), it returns @code{nil}.
|
|
850 The value of @var{dirname} may be either a directory name (such as
|
|
851 @file{/foo/}) or the file name of a file which is a directory
|
|
852 (such as @file{/foo}, without the final slash).
|
|
853
|
|
854 Example: after the following,
|
|
855
|
|
856 @example
|
|
857 (file-accessible-directory-p "/foo")
|
|
858 @result{} nil
|
|
859 @end example
|
|
860
|
|
861 @noindent
|
|
862 we can deduce that any attempt to read a file in @file{/foo/} will
|
|
863 give an error.
|
|
864 @end defun
|
|
865
|
|
866 @defun access-file filename string
|
|
867 This function opens file @var{filename} for reading, then closes it and
|
|
868 returns @code{nil}. However, if the open fails, it signals an error
|
|
869 using @var{string} as the error message text.
|
|
870 @end defun
|
|
871
|
|
872 @defun file-ownership-preserved-p filename
|
|
873 This function returns @code{t} if deleting the file @var{filename} and
|
|
874 then creating it anew would keep the file's owner unchanged. It also
|
|
875 returns @code{t} for nonexistent files.
|
|
876
|
|
877 If @var{filename} is a symbolic link, then, unlike the other functions
|
|
878 discussed here, @code{file-ownership-preserved-p} does @emph{not}
|
|
879 replace @var{filename} with its target. However, it does recursively
|
|
880 follow symbolic links at all levels of parent directories.
|
|
881 @end defun
|
|
882
|
|
883 @defun file-newer-than-file-p filename1 filename2
|
|
884 @cindex file age
|
|
885 @cindex file modification time
|
|
886 This function returns @code{t} if the file @var{filename1} is
|
|
887 newer than file @var{filename2}. If @var{filename1} does not
|
|
888 exist, it returns @code{nil}. If @var{filename1} does exist, but
|
|
889 @var{filename2} does not, it returns @code{t}.
|
|
890
|
|
891 In the following example, assume that the file @file{aug-19} was written
|
|
892 on the 19th, @file{aug-20} was written on the 20th, and the file
|
|
893 @file{no-file} doesn't exist at all.
|
|
894
|
|
895 @example
|
|
896 @group
|
|
897 (file-newer-than-file-p "aug-19" "aug-20")
|
|
898 @result{} nil
|
|
899 @end group
|
|
900 @group
|
|
901 (file-newer-than-file-p "aug-20" "aug-19")
|
|
902 @result{} t
|
|
903 @end group
|
|
904 @group
|
|
905 (file-newer-than-file-p "aug-19" "no-file")
|
|
906 @result{} t
|
|
907 @end group
|
|
908 @group
|
|
909 (file-newer-than-file-p "no-file" "aug-19")
|
|
910 @result{} nil
|
|
911 @end group
|
|
912 @end example
|
|
913
|
|
914 You can use @code{file-attributes} to get a file's last modification
|
|
915 time as a list of two numbers. @xref{File Attributes}.
|
|
916 @end defun
|
|
917
|
|
918 @node Kinds of Files
|
|
919 @comment node-name, next, previous, up
|
|
920 @subsection Distinguishing Kinds of Files
|
|
921
|
|
922 This section describes how to distinguish various kinds of files, such
|
|
923 as directories, symbolic links, and ordinary files.
|
|
924
|
|
925 @defun file-symlink-p filename
|
|
926 @cindex file symbolic links
|
|
927 If the file @var{filename} is a symbolic link, the
|
|
928 @code{file-symlink-p} function returns the (non-recursive) link target
|
|
929 as a string. (Determining the file name that the link points to from
|
|
930 the target is nontrivial.) First, this function recursively follows
|
|
931 symbolic links at all levels of parent directories.
|
|
932
|
|
933 If the file @var{filename} is not a symbolic link (or there is no such file),
|
|
934 @code{file-symlink-p} returns @code{nil}.
|
|
935
|
|
936 @example
|
|
937 @group
|
|
938 (file-symlink-p "foo")
|
|
939 @result{} nil
|
|
940 @end group
|
|
941 @group
|
|
942 (file-symlink-p "sym-link")
|
|
943 @result{} "foo"
|
|
944 @end group
|
|
945 @group
|
|
946 (file-symlink-p "sym-link2")
|
|
947 @result{} "sym-link"
|
|
948 @end group
|
|
949 @group
|
|
950 (file-symlink-p "/bin")
|
|
951 @result{} "/pub/bin"
|
|
952 @end group
|
|
953 @end example
|
|
954
|
|
955 @c !!! file-symlink-p: should show output of ls -l for comparison
|
|
956 @end defun
|
|
957
|
|
958 The next two functions recursively follow symbolic links at
|
|
959 all levels for @var{filename}.
|
|
960
|
|
961 @defun file-directory-p filename
|
|
962 This function returns @code{t} if @var{filename} is the name of an
|
|
963 existing directory, @code{nil} otherwise.
|
|
964
|
|
965 @example
|
|
966 @group
|
|
967 (file-directory-p "~rms")
|
|
968 @result{} t
|
|
969 @end group
|
|
970 @group
|
|
971 (file-directory-p "~rms/lewis/files.texi")
|
|
972 @result{} nil
|
|
973 @end group
|
|
974 @group
|
|
975 (file-directory-p "~rms/lewis/no-such-file")
|
|
976 @result{} nil
|
|
977 @end group
|
|
978 @group
|
|
979 (file-directory-p "$HOME")
|
|
980 @result{} nil
|
|
981 @end group
|
|
982 @group
|
|
983 (file-directory-p
|
|
984 (substitute-in-file-name "$HOME"))
|
|
985 @result{} t
|
|
986 @end group
|
|
987 @end example
|
|
988 @end defun
|
|
989
|
|
990 @defun file-regular-p filename
|
|
991 This function returns @code{t} if the file @var{filename} exists and is
|
|
992 a regular file (not a directory, named pipe, terminal, or
|
|
993 other I/O device).
|
|
994 @end defun
|
|
995
|
|
996 @node Truenames
|
|
997 @subsection Truenames
|
|
998 @cindex truename (of file)
|
|
999
|
|
1000 @c Emacs 19 features
|
|
1001 The @dfn{truename} of a file is the name that you get by following
|
|
1002 symbolic links at all levels until none remain, then simplifying away
|
|
1003 @samp{.}@: and @samp{..}@: appearing as name components. This results
|
|
1004 in a sort of canonical name for the file. A file does not always have a
|
|
1005 unique truename; the number of distinct truenames a file has is equal to
|
|
1006 the number of hard links to the file. However, truenames are useful
|
|
1007 because they eliminate symbolic links as a cause of name variation.
|
|
1008
|
|
1009 @defun file-truename filename
|
|
1010 The function @code{file-truename} returns the truename of the file
|
|
1011 @var{filename}. The argument must be an absolute file name.
|
|
1012
|
|
1013 This function does not expand environment variables. Only
|
|
1014 @code{substitute-in-file-name} does that. @xref{Definition of
|
|
1015 substitute-in-file-name}.
|
|
1016
|
|
1017 If you may need to follow symbolic links preceding @samp{..}@:
|
|
1018 appearing as a name component, you should make sure to call
|
|
1019 @code{file-truename} without prior direct or indirect calls to
|
|
1020 @code{expand-file-name}, as otherwise the file name component
|
|
1021 immediately preceding @samp{..} will be ``simplified away'' before
|
|
1022 @code{file-truename} is called. To eliminate the need for a call to
|
|
1023 @code{expand-file-name}, @code{file-truename} handles @samp{~} in the
|
|
1024 same way that @code{expand-file-name} does. @xref{File Name
|
|
1025 Expansion,, Functions that Expand Filenames}.
|
|
1026 @end defun
|
|
1027
|
|
1028 @defun file-chase-links filename &optional limit
|
|
1029 This function follows symbolic links, starting with @var{filename},
|
|
1030 until it finds a file name which is not the name of a symbolic link.
|
|
1031 Then it returns that file name. This function does @emph{not} follow
|
|
1032 symbolic links at the level of parent directories.
|
|
1033
|
|
1034 If you specify a number for @var{limit}, then after chasing through
|
|
1035 that many links, the function just returns what it has even if that is
|
|
1036 still a symbolic link.
|
|
1037 @end defun
|
|
1038
|
|
1039 To illustrate the difference between @code{file-chase-links} and
|
|
1040 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
|
|
1041 the directory @file{/home/foo}, and @file{/home/foo/hello} is an
|
|
1042 ordinary file (or at least, not a symbolic link) or nonexistent. Then
|
|
1043 we would have:
|
|
1044
|
|
1045 @example
|
|
1046 (file-chase-links "/usr/foo/hello")
|
|
1047 ;; @r{This does not follow the links in the parent directories.}
|
|
1048 @result{} "/usr/foo/hello"
|
|
1049 (file-truename "/usr/foo/hello")
|
|
1050 ;; @r{Assuming that @file{/home} is not a symbolic link.}
|
|
1051 @result{} "/home/foo/hello"
|
|
1052 @end example
|
|
1053
|
|
1054 @xref{Buffer File Name}, for related information.
|
|
1055
|
|
1056 @node File Attributes
|
|
1057 @comment node-name, next, previous, up
|
|
1058 @subsection Other Information about Files
|
|
1059
|
|
1060 This section describes the functions for getting detailed information
|
|
1061 about a file, other than its contents. This information includes the
|
|
1062 mode bits that control access permission, the owner and group numbers,
|
|
1063 the number of names, the inode number, the size, and the times of access
|
|
1064 and modification.
|
|
1065
|
|
1066 @defun file-modes filename
|
|
1067 @cindex permission
|
|
1068 @cindex file attributes
|
|
1069 This function returns the mode bits of @var{filename}, as an integer.
|
|
1070 The mode bits are also called the file permissions, and they specify
|
|
1071 access control in the usual Unix fashion. If the low-order bit is 1,
|
|
1072 then the file is executable by all users, if the second-lowest-order bit
|
|
1073 is 1, then the file is writable by all users, etc.
|
|
1074
|
|
1075 The highest value returnable is 4095 (7777 octal), meaning that
|
|
1076 everyone has read, write, and execute permission, that the @acronym{SUID} bit
|
|
1077 is set for both others and group, and that the sticky bit is set.
|
|
1078
|
|
1079 If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
|
|
1080
|
|
1081 This function recursively follows symbolic links at all levels.
|
|
1082
|
|
1083 @example
|
|
1084 @group
|
|
1085 (file-modes "~/junk/diffs")
|
|
1086 @result{} 492 ; @r{Decimal integer.}
|
|
1087 @end group
|
|
1088 @group
|
|
1089 (format "%o" 492)
|
|
1090 @result{} "754" ; @r{Convert to octal.}
|
|
1091 @end group
|
|
1092
|
|
1093 @group
|
|
1094 (set-file-modes "~/junk/diffs" 438)
|
|
1095 @result{} nil
|
|
1096 @end group
|
|
1097
|
|
1098 @group
|
|
1099 (format "%o" 438)
|
|
1100 @result{} "666" ; @r{Convert to octal.}
|
|
1101 @end group
|
|
1102
|
|
1103 @group
|
|
1104 % ls -l diffs
|
|
1105 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
|
|
1106 @end group
|
|
1107 @end example
|
|
1108 @end defun
|
|
1109
|
|
1110 If the @var{filename} argument to the next two functions is a symbolic
|
|
1111 link, then these function do @emph{not} replace it with its target.
|
|
1112 However, they both recursively follow symbolic links at all levels of
|
|
1113 parent directories.
|
|
1114
|
|
1115 @defun file-nlinks filename
|
|
1116 This functions returns the number of names (i.e., hard links) that
|
|
1117 file @var{filename} has. If the file does not exist, then this function
|
|
1118 returns @code{nil}. Note that symbolic links have no effect on this
|
|
1119 function, because they are not considered to be names of the files they
|
|
1120 link to.
|
|
1121
|
|
1122 @example
|
|
1123 @group
|
|
1124 % ls -l foo*
|
|
1125 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
|
|
1126 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
|
|
1127 @end group
|
|
1128
|
|
1129 @group
|
|
1130 (file-nlinks "foo")
|
|
1131 @result{} 2
|
|
1132 @end group
|
|
1133 @group
|
|
1134 (file-nlinks "doesnt-exist")
|
|
1135 @result{} nil
|
|
1136 @end group
|
|
1137 @end example
|
|
1138 @end defun
|
|
1139
|
|
1140 @defun file-attributes filename &optional id-format
|
|
1141 @anchor{Definition of file-attributes}
|
|
1142 This function returns a list of attributes of file @var{filename}. If
|
|
1143 the specified file cannot be opened, it returns @code{nil}.
|
|
1144 The optional parameter @var{id-format} specifies the preferred format
|
|
1145 of attributes @acronym{UID} and @acronym{GID} (see below)---the
|
|
1146 valid values are @code{'string} and @code{'integer}. The latter is
|
|
1147 the default, but we plan to change that, so you should specify a
|
|
1148 non-@code{nil} value for @var{id-format} if you use the returned
|
|
1149 @acronym{UID} or @acronym{GID}.
|
|
1150
|
|
1151 The elements of the list, in order, are:
|
|
1152
|
|
1153 @enumerate 0
|
|
1154 @item
|
|
1155 @code{t} for a directory, a string for a symbolic link (the name
|
|
1156 linked to), or @code{nil} for a text file.
|
|
1157
|
|
1158 @c Wordy so as to prevent an overfull hbox. --rjc 15mar92
|
|
1159 @item
|
|
1160 The number of names the file has. Alternate names, also known as hard
|
|
1161 links, can be created by using the @code{add-name-to-file} function
|
|
1162 (@pxref{Changing Files}).
|
|
1163
|
|
1164 @item
|
|
1165 The file's @acronym{UID}, normally as a string. However, if it does
|
|
1166 not correspond to a named user, the value is an integer or a floating
|
|
1167 point number.
|
|
1168
|
|
1169 @item
|
|
1170 The file's @acronym{GID}, likewise.
|
|
1171
|
|
1172 @item
|
|
1173 The time of last access, as a list of two integers.
|
|
1174 The first integer has the high-order 16 bits of time,
|
|
1175 the second has the low 16 bits. (This is similar to the
|
|
1176 value of @code{current-time}; see @ref{Time of Day}.)
|
|
1177
|
|
1178 @item
|
|
1179 The time of last modification as a list of two integers (as above).
|
|
1180 @cindex modification time of file
|
|
1181
|
|
1182 @item
|
|
1183 The time of last status change as a list of two integers (as above).
|
|
1184
|
|
1185 @item
|
|
1186 The size of the file in bytes. If the size is too large to fit in a
|
|
1187 Lisp integer, this is a floating point number.
|
|
1188
|
|
1189 @item
|
|
1190 The file's modes, as a string of ten letters or dashes,
|
|
1191 as in @samp{ls -l}.
|
|
1192
|
|
1193 @item
|
|
1194 @code{t} if the file's @acronym{GID} would change if file were
|
|
1195 deleted and recreated; @code{nil} otherwise.
|
|
1196
|
|
1197 @item
|
|
1198 The file's inode number. If possible, this is an integer. If the inode
|
|
1199 number is too large to be represented as an integer in Emacs Lisp, then
|
|
1200 the value has the form @code{(@var{high} . @var{low})}, where @var{low}
|
|
1201 holds the low 16 bits.
|
|
1202
|
|
1203 @item
|
|
1204 The file system number of the file system that the file is in.
|
|
1205 Depending on the magnitude of the value, this can be either an integer
|
|
1206 or a cons cell, in the same manner as the inode number. This element
|
|
1207 and the file's inode number together give enough information to
|
|
1208 distinguish any two files on the system---no two files can have the same
|
|
1209 values for both of these numbers.
|
|
1210 @end enumerate
|
|
1211
|
|
1212 For example, here are the file attributes for @file{files.texi}:
|
|
1213
|
|
1214 @example
|
|
1215 @group
|
|
1216 (file-attributes "files.texi" 'string)
|
|
1217 @result{} (nil 1 "lh" "users"
|
|
1218 (8489 20284)
|
|
1219 (8489 20284)
|
|
1220 (8489 20285)
|
|
1221 14906 "-rw-rw-rw-"
|
|
1222 nil 129500 -32252)
|
|
1223 @end group
|
|
1224 @end example
|
|
1225
|
|
1226 @noindent
|
|
1227 and here is how the result is interpreted:
|
|
1228
|
|
1229 @table @code
|
|
1230 @item nil
|
|
1231 is neither a directory nor a symbolic link.
|
|
1232
|
|
1233 @item 1
|
|
1234 has only one name (the name @file{files.texi} in the current default
|
|
1235 directory).
|
|
1236
|
|
1237 @item "lh"
|
|
1238 is owned by the user with name "lh".
|
|
1239
|
|
1240 @item "users"
|
|
1241 is in the group with name "users".
|
|
1242
|
|
1243 @item (8489 20284)
|
|
1244 was last accessed on Aug 19 00:09.
|
|
1245
|
|
1246 @item (8489 20284)
|
|
1247 was last modified on Aug 19 00:09.
|
|
1248
|
|
1249 @item (8489 20285)
|
|
1250 last had its inode changed on Aug 19 00:09.
|
|
1251
|
|
1252 @item 14906
|
|
1253 is 14906 bytes long. (It may not contain 14906 characters, though,
|
|
1254 if some of the bytes belong to multibyte sequences.)
|
|
1255
|
|
1256 @item "-rw-rw-rw-"
|
|
1257 has a mode of read and write access for the owner, group, and world.
|
|
1258
|
|
1259 @item nil
|
|
1260 would retain the same @acronym{GID} if it were recreated.
|
|
1261
|
|
1262 @item 129500
|
|
1263 has an inode number of 129500.
|
|
1264 @item -32252
|
|
1265 is on file system number -32252.
|
|
1266 @end table
|
|
1267 @end defun
|
|
1268
|
|
1269 @node Locating Files
|
|
1270 @subsection How to Locate Files in Standard Places
|
|
1271 @cindex locate file in path
|
|
1272 @cindex find file in path
|
|
1273
|
|
1274 This section explains how to search for a file in a list of
|
|
1275 directories (a @dfn{path}). One example is when you need to look for
|
|
1276 a program's executable file, e.g., to find out whether a given program
|
|
1277 is installed on the user's system. Another example is the search for
|
|
1278 Lisp libraries (@pxref{Library Search}). Such searches generally need
|
|
1279 to try various possible file name extensions, in addition to various
|
|
1280 possible directories. Emacs provides a function for such a
|
|
1281 generalized search for a file.
|
|
1282
|
|
1283 @defun locate-file filename path &optional suffixes predicate
|
|
1284 This function searches for a file whose name is @var{filename} in a
|
|
1285 list of directories given by @var{path}, trying the suffixes in
|
|
1286 @var{suffixes}. If it finds such a file, it returns the full
|
|
1287 @dfn{absolute file name} of the file (@pxref{Relative File Names});
|
|
1288 otherwise it returns @code{nil}.
|
|
1289
|
|
1290 The optional argument @var{suffixes} gives the list of file-name
|
|
1291 suffixes to append to @var{filename} when searching.
|
|
1292 @code{locate-file} tries each possible directory with each of these
|
|
1293 suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there
|
|
1294 are no suffixes, and @var{filename} is used only as-is. Typical
|
|
1295 values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
|
|
1296 Creation, exec-suffixes}), @code{load-suffixes},
|
|
1297 @code{load-file-rep-suffixes} and the return value of the function
|
|
1298 @code{get-load-suffixes} (@pxref{Load Suffixes}).
|
|
1299
|
|
1300 Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
|
|
1301 Creation, exec-path}) when looking for executable programs or
|
|
1302 @code{load-path} (@pxref{Library Search, load-path}) when looking for
|
|
1303 Lisp files. If @var{filename} is absolute, @var{path} has no effect,
|
|
1304 but the suffixes in @var{suffixes} are still tried.
|
|
1305
|
|
1306 The optional argument @var{predicate}, if non-@code{nil}, specifies
|
|
1307 the predicate function to use for testing whether a candidate file is
|
|
1308 suitable. The predicate function is passed the candidate file name as
|
|
1309 its single argument. If @var{predicate} is @code{nil} or unspecified,
|
|
1310 @code{locate-file} uses @code{file-readable-p} as the default
|
|
1311 predicate. Useful non-default predicates include
|
|
1312 @code{file-executable-p}, @code{file-directory-p}, and other
|
|
1313 predicates described in @ref{Kinds of Files}.
|
|
1314
|
|
1315 For compatibility, @var{predicate} can also be one of the symbols
|
|
1316 @code{executable}, @code{readable}, @code{writable}, @code{exists}, or
|
|
1317 a list of one or more of these symbols.
|
|
1318 @end defun
|
|
1319
|
|
1320 @defun executable-find program
|
|
1321 This function searches for the executable file of the named
|
|
1322 @var{program} and returns the full absolute name of the executable,
|
|
1323 including its file-name extensions, if any. It returns @code{nil} if
|
|
1324 the file is not found. The functions searches in all the directories
|
|
1325 in @code{exec-path} and tries all the file-name extensions in
|
|
1326 @code{exec-suffixes}.
|
|
1327 @end defun
|
|
1328
|
|
1329 @node Changing Files
|
|
1330 @section Changing File Names and Attributes
|
|
1331 @c @cindex renaming files Duplicates rename-file
|
|
1332 @cindex copying files
|
|
1333 @cindex deleting files
|
|
1334 @cindex linking files
|
|
1335 @cindex setting modes of files
|
|
1336
|
|
1337 The functions in this section rename, copy, delete, link, and set the
|
|
1338 modes of files.
|
|
1339
|
|
1340 In the functions that have an argument @var{newname}, if a file by the
|
|
1341 name of @var{newname} already exists, the actions taken depend on the
|
|
1342 value of the argument @var{ok-if-already-exists}:
|
|
1343
|
|
1344 @itemize @bullet
|
|
1345 @item
|
|
1346 Signal a @code{file-already-exists} error if
|
|
1347 @var{ok-if-already-exists} is @code{nil}.
|
|
1348
|
|
1349 @item
|
|
1350 Request confirmation if @var{ok-if-already-exists} is a number.
|
|
1351
|
|
1352 @item
|
|
1353 Replace the old file without confirmation if @var{ok-if-already-exists}
|
|
1354 is any other value.
|
|
1355 @end itemize
|
|
1356
|
|
1357 The next four commands all recursively follow symbolic links at all
|
|
1358 levels of parent directories for their first argument, but, if that
|
|
1359 argument is itself a symbolic link, then only @code{copy-file}
|
|
1360 replaces it with its (recursive) target.
|
|
1361
|
|
1362 @deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
|
|
1363 @cindex file with multiple names
|
|
1364 @cindex file hard link
|
|
1365 This function gives the file named @var{oldname} the additional name
|
|
1366 @var{newname}. This means that @var{newname} becomes a new ``hard
|
|
1367 link'' to @var{oldname}.
|
|
1368
|
|
1369 In the first part of the following example, we list two files,
|
|
1370 @file{foo} and @file{foo3}.
|
|
1371
|
|
1372 @example
|
|
1373 @group
|
|
1374 % ls -li fo*
|
|
1375 81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
|
|
1376 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
|
|
1377 @end group
|
|
1378 @end example
|
|
1379
|
|
1380 Now we create a hard link, by calling @code{add-name-to-file}, then list
|
|
1381 the files again. This shows two names for one file, @file{foo} and
|
|
1382 @file{foo2}.
|
|
1383
|
|
1384 @example
|
|
1385 @group
|
|
1386 (add-name-to-file "foo" "foo2")
|
|
1387 @result{} nil
|
|
1388 @end group
|
|
1389
|
|
1390 @group
|
|
1391 % ls -li fo*
|
|
1392 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
|
|
1393 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
|
|
1394 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
|
|
1395 @end group
|
|
1396 @end example
|
|
1397
|
|
1398 Finally, we evaluate the following:
|
|
1399
|
|
1400 @example
|
|
1401 (add-name-to-file "foo" "foo3" t)
|
|
1402 @end example
|
|
1403
|
|
1404 @noindent
|
|
1405 and list the files again. Now there are three names
|
|
1406 for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old
|
|
1407 contents of @file{foo3} are lost.
|
|
1408
|
|
1409 @example
|
|
1410 @group
|
|
1411 (add-name-to-file "foo1" "foo3")
|
|
1412 @result{} nil
|
|
1413 @end group
|
|
1414
|
|
1415 @group
|
|
1416 % ls -li fo*
|
|
1417 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
|
|
1418 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
|
|
1419 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
|
|
1420 @end group
|
|
1421 @end example
|
|
1422
|
|
1423 This function is meaningless on operating systems where multiple names
|
|
1424 for one file are not allowed. Some systems implement multiple names
|
|
1425 by copying the file instead.
|
|
1426
|
|
1427 See also @code{file-nlinks} in @ref{File Attributes}.
|
|
1428 @end deffn
|
|
1429
|
|
1430 @deffn Command rename-file filename newname &optional ok-if-already-exists
|
|
1431 This command renames the file @var{filename} as @var{newname}.
|
|
1432
|
|
1433 If @var{filename} has additional names aside from @var{filename}, it
|
|
1434 continues to have those names. In fact, adding the name @var{newname}
|
|
1435 with @code{add-name-to-file} and then deleting @var{filename} has the
|
|
1436 same effect as renaming, aside from momentary intermediate states.
|
|
1437 @end deffn
|
|
1438
|
|
1439 @deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid
|
|
1440 This command copies the file @var{oldname} to @var{newname}. An
|
|
1441 error is signaled if @var{oldname} does not exist. If @var{newname}
|
|
1442 names a directory, it copies @var{oldname} into that directory,
|
|
1443 preserving its final name component.
|
|
1444
|
|
1445 If @var{time} is non-@code{nil}, then this function gives the new file
|
|
1446 the same last-modified time that the old one has. (This works on only
|
|
1447 some operating systems.) If setting the time gets an error,
|
|
1448 @code{copy-file} signals a @code{file-date-error} error. In an
|
|
1449 interactive call, a prefix argument specifies a non-@code{nil} value
|
|
1450 for @var{time}.
|
|
1451
|
|
1452 This function copies the file modes, too.
|
|
1453
|
|
1454 If argument @var{preserve-uid-gid} is @code{nil}, we let the operating
|
|
1455 system decide the user and group ownership of the new file (this is
|
|
1456 usually set to the user running Emacs). If @var{preserve-uid-gid} is
|
|
1457 non-@code{nil}, we attempt to copy the user and group ownership of the
|
|
1458 file. This works only on some operating systems, and only if you have
|
|
1459 the correct permissions to do so.
|
|
1460 @end deffn
|
|
1461
|
|
1462 @deffn Command make-symbolic-link filename newname &optional ok-if-exists
|
|
1463 @pindex ln
|
|
1464 @kindex file-already-exists
|
|
1465 This command makes a symbolic link to @var{filename}, named
|
|
1466 @var{newname}. This is like the shell command @samp{ln -s
|
|
1467 @var{filename} @var{newname}}.
|
|
1468
|
|
1469 This function is not available on systems that don't support symbolic
|
|
1470 links.
|
|
1471 @end deffn
|
|
1472
|
|
1473 @deffn Command delete-file filename
|
|
1474 @pindex rm
|
|
1475 This command deletes the file @var{filename}, like the shell command
|
|
1476 @samp{rm @var{filename}}. If the file has multiple names, it continues
|
|
1477 to exist under the other names.
|
|
1478
|
|
1479 A suitable kind of @code{file-error} error is signaled if the file does
|
|
1480 not exist, or is not deletable. (On Unix and GNU/Linux, a file is
|
|
1481 deletable if its directory is writable.)
|
|
1482
|
|
1483 If @var{filename} is a symbolic link, @code{delete-file} does not
|
|
1484 replace it with its target, but it does follow symbolic links at all
|
|
1485 levels of parent directories.
|
|
1486
|
|
1487 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
|
|
1488 @end deffn
|
|
1489
|
|
1490 @defun define-logical-name varname string
|
|
1491 This function defines the logical name @var{varname} to have the value
|
|
1492 @var{string}. It is available only on VMS.
|
|
1493 @end defun
|
|
1494
|
|
1495 @defun set-file-modes filename mode
|
|
1496 This function sets mode bits of @var{filename} to @var{mode} (which
|
|
1497 must be an integer). Only the low 12 bits of @var{mode} are used.
|
|
1498 This function recursively follows symbolic links at all levels for
|
|
1499 @var{filename}.
|
|
1500 @end defun
|
|
1501
|
|
1502 @c Emacs 19 feature
|
|
1503 @defun set-default-file-modes mode
|
|
1504 @cindex umask
|
|
1505 This function sets the default file protection for new files created by
|
|
1506 Emacs and its subprocesses. Every file created with Emacs initially has
|
|
1507 this protection, or a subset of it (@code{write-region} will not give a
|
|
1508 file execute permission even if the default file protection allows
|
|
1509 execute permission). On Unix and GNU/Linux, the default protection is
|
|
1510 the bitwise complement of the ``umask'' value.
|
|
1511
|
|
1512 The argument @var{mode} must be an integer. On most systems, only the
|
|
1513 low 9 bits of @var{mode} are meaningful. You can use the Lisp construct
|
|
1514 for octal character codes to enter @var{mode}; for example,
|
|
1515
|
|
1516 @example
|
|
1517 (set-default-file-modes ?\644)
|
|
1518 @end example
|
|
1519
|
|
1520 Saving a modified version of an existing file does not count as creating
|
|
1521 the file; it preserves the existing file's mode, whatever that is. So
|
|
1522 the default file protection has no effect.
|
|
1523 @end defun
|
|
1524
|
|
1525 @defun default-file-modes
|
|
1526 This function returns the current default protection value.
|
|
1527 @end defun
|
|
1528
|
|
1529 @defun set-file-times filename &optional time
|
|
1530 This function sets the access and modification times of @var{filename}
|
|
1531 to @var{time}. The return value is @code{t} if the times are successfully
|
|
1532 set, otherwise it is @code{nil}. @var{time} defaults to the current
|
|
1533 time and must be in the format returned by @code{current-time}
|
|
1534 (@pxref{Time of Day}).
|
|
1535 @end defun
|
|
1536
|
|
1537 @cindex MS-DOS and file modes
|
|
1538 @cindex file modes and MS-DOS
|
|
1539 On MS-DOS, there is no such thing as an ``executable'' file mode bit.
|
|
1540 So Emacs considers a file executable if its name ends in one of the
|
|
1541 standard executable extensions, such as @file{.com}, @file{.bat},
|
|
1542 @file{.exe}, and some others. Files that begin with the Unix-standard
|
|
1543 @samp{#!} signature, such as shell and Perl scripts, are also considered
|
|
1544 as executable files. This is reflected in the values returned by
|
|
1545 @code{file-modes} and @code{file-attributes}. Directories are also
|
|
1546 reported with executable bit set, for compatibility with Unix.
|
|
1547
|
|
1548 @node File Names
|
|
1549 @section File Names
|
|
1550 @cindex file names
|
|
1551
|
|
1552 Files are generally referred to by their names, in Emacs as elsewhere.
|
|
1553 File names in Emacs are represented as strings. The functions that
|
|
1554 operate on a file all expect a file name argument.
|
|
1555
|
|
1556 In addition to operating on files themselves, Emacs Lisp programs
|
|
1557 often need to operate on file names; i.e., to take them apart and to use
|
|
1558 part of a name to construct related file names. This section describes
|
|
1559 how to manipulate file names.
|
|
1560
|
|
1561 The functions in this section do not actually access files, so they
|
|
1562 can operate on file names that do not refer to an existing file or
|
|
1563 directory.
|
|
1564
|
|
1565 On MS-DOS and MS-Windows, these functions (like the function that
|
|
1566 actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
|
|
1567 where backslashes separate the components, as well as Unix syntax; but
|
|
1568 they always return Unix syntax. On VMS, these functions (and the ones
|
|
1569 that operate on files) understand both VMS file-name syntax and Unix
|
|
1570 syntax. This enables Lisp programs to specify file names in Unix syntax
|
|
1571 and work properly on all systems without change.
|
|
1572
|
|
1573 @menu
|
|
1574 * File Name Components:: The directory part of a file name, and the rest.
|
|
1575 * Relative File Names:: Some file names are relative to a current directory.
|
|
1576 * Directory Names:: A directory's name as a directory
|
|
1577 is different from its name as a file.
|
|
1578 * File Name Expansion:: Converting relative file names to absolute ones.
|
|
1579 * Unique File Names:: Generating names for temporary files.
|
|
1580 * File Name Completion:: Finding the completions for a given file name.
|
|
1581 * Standard File Names:: If your package uses a fixed file name,
|
|
1582 how to handle various operating systems simply.
|
|
1583 @end menu
|
|
1584
|
|
1585 @node File Name Components
|
|
1586 @subsection File Name Components
|
|
1587 @cindex directory part (of file name)
|
|
1588 @cindex nondirectory part (of file name)
|
|
1589 @cindex version number (in file name)
|
|
1590
|
|
1591 The operating system groups files into directories. To specify a
|
|
1592 file, you must specify the directory and the file's name within that
|
|
1593 directory. Therefore, Emacs considers a file name as having two main
|
|
1594 parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
|
|
1595 (or @dfn{file name within the directory}). Either part may be empty.
|
|
1596 Concatenating these two parts reproduces the original file name.
|
|
1597
|
|
1598 On most systems, the directory part is everything up to and including
|
|
1599 the last slash (backslash is also allowed in input on MS-DOS or
|
|
1600 MS-Windows); the nondirectory part is the rest. The rules in VMS syntax
|
|
1601 are complicated.
|
|
1602
|
|
1603 For some purposes, the nondirectory part is further subdivided into
|
|
1604 the name proper and the @dfn{version number}. On most systems, only
|
|
1605 backup files have version numbers in their names. On VMS, every file
|
|
1606 has a version number, but most of the time the file name actually used
|
|
1607 in Emacs omits the version number, so that version numbers in Emacs are
|
|
1608 found mostly in directory lists.
|
|
1609
|
|
1610 @defun file-name-directory filename
|
|
1611 This function returns the directory part of @var{filename}, as a
|
|
1612 directory name (@pxref{Directory Names}), or @code{nil} if
|
|
1613 @var{filename} does not include a directory part.
|
|
1614
|
|
1615 On GNU and Unix systems, a string returned by this function always
|
|
1616 ends in a slash. On MS-DOS it can also end in a colon. On VMS, it
|
|
1617 returns a string ending in one of the three characters @samp{:},
|
|
1618 @samp{]}, or @samp{>}.
|
|
1619
|
|
1620 @example
|
|
1621 @group
|
|
1622 (file-name-directory "lewis/foo") ; @r{Unix example}
|
|
1623 @result{} "lewis/"
|
|
1624 @end group
|
|
1625 @group
|
|
1626 (file-name-directory "foo") ; @r{Unix example}
|
|
1627 @result{} nil
|
|
1628 @end group
|
|
1629 @group
|
|
1630 (file-name-directory "[X]FOO.TMP") ; @r{VMS example}
|
|
1631 @result{} "[X]"
|
|
1632 @end group
|
|
1633 @end example
|
|
1634 @end defun
|
|
1635
|
|
1636 @defun file-name-nondirectory filename
|
|
1637 This function returns the nondirectory part of @var{filename}.
|
|
1638
|
|
1639 @example
|
|
1640 @group
|
|
1641 (file-name-nondirectory "lewis/foo")
|
|
1642 @result{} "foo"
|
|
1643 @end group
|
|
1644 @group
|
|
1645 (file-name-nondirectory "foo")
|
|
1646 @result{} "foo"
|
|
1647 @end group
|
|
1648 @group
|
|
1649 (file-name-nondirectory "lewis/")
|
|
1650 @result{} ""
|
|
1651 @end group
|
|
1652 @group
|
|
1653 ;; @r{The following example is accurate only on VMS.}
|
|
1654 (file-name-nondirectory "[X]FOO.TMP")
|
|
1655 @result{} "FOO.TMP"
|
|
1656 @end group
|
|
1657 @end example
|
|
1658 @end defun
|
|
1659
|
|
1660 @defun file-name-sans-versions filename &optional keep-backup-version
|
|
1661 This function returns @var{filename} with any file version numbers,
|
|
1662 backup version numbers, or trailing tildes discarded.
|
|
1663
|
|
1664 If @var{keep-backup-version} is non-@code{nil}, then true file version
|
|
1665 numbers understood as such by the file system are discarded from the
|
|
1666 return value, but backup version numbers are kept.
|
|
1667
|
|
1668 @example
|
|
1669 @group
|
|
1670 (file-name-sans-versions "~rms/foo.~1~")
|
|
1671 @result{} "~rms/foo"
|
|
1672 @end group
|
|
1673 @group
|
|
1674 (file-name-sans-versions "~rms/foo~")
|
|
1675 @result{} "~rms/foo"
|
|
1676 @end group
|
|
1677 @group
|
|
1678 (file-name-sans-versions "~rms/foo")
|
|
1679 @result{} "~rms/foo"
|
|
1680 @end group
|
|
1681 @group
|
|
1682 ;; @r{The following example applies to VMS only.}
|
|
1683 (file-name-sans-versions "foo;23")
|
|
1684 @result{} "foo"
|
|
1685 @end group
|
|
1686 @end example
|
|
1687 @end defun
|
|
1688
|
|
1689 @defun file-name-extension filename &optional period
|
|
1690 This function returns @var{filename}'s final ``extension,'' if any,
|
|
1691 after applying @code{file-name-sans-versions} to remove any
|
|
1692 version/backup part. The extension, in a file name, is the part that
|
|
1693 starts with the last @samp{.} in the last name component (minus
|
|
1694 any version/backup part).
|
|
1695
|
|
1696 This function returns @code{nil} for extensionless file names such as
|
|
1697 @file{foo}. It returns @code{""} for null extensions, as in
|
|
1698 @file{foo.}. If the last component of a file name begins with a
|
|
1699 @samp{.}, that @samp{.} doesn't count as the beginning of an
|
|
1700 extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
|
|
1701 @samp{.emacs}.
|
|
1702
|
|
1703 If @var{period} is non-@code{nil}, then the returned value includes
|
|
1704 the period that delimits the extension, and if @var{filename} has no
|
|
1705 extension, the value is @code{""}.
|
|
1706 @end defun
|
|
1707
|
|
1708 @defun file-name-sans-extension filename
|
|
1709 This function returns @var{filename} minus its extension, if any. The
|
|
1710 version/backup part, if present, is only removed if the file has an
|
|
1711 extension. For example,
|
|
1712
|
|
1713 @example
|
|
1714 (file-name-sans-extension "foo.lose.c")
|
|
1715 @result{} "foo.lose"
|
|
1716 (file-name-sans-extension "big.hack/foo")
|
|
1717 @result{} "big.hack/foo"
|
|
1718 (file-name-sans-extension "/my/home/.emacs")
|
|
1719 @result{} "/my/home/.emacs"
|
|
1720 (file-name-sans-extension "/my/home/.emacs.el")
|
|
1721 @result{} "/my/home/.emacs"
|
|
1722 (file-name-sans-extension "~/foo.el.~3~")
|
|
1723 @result{} "~/foo"
|
|
1724 (file-name-sans-extension "~/foo.~3~")
|
|
1725 @result{} "~/foo.~3~"
|
|
1726 @end example
|
|
1727
|
|
1728 Note that the @samp{.~3~} in the two last examples is the backup part,
|
|
1729 not an extension.
|
|
1730 @end defun
|
|
1731
|
|
1732 @ignore
|
|
1733 Andrew Innes says that this
|
|
1734
|
|
1735 @c @defvar directory-sep-char
|
|
1736 This variable holds the character that Emacs normally uses to separate
|
|
1737 file name components. The default value is @code{?/}, but on MS-Windows
|
|
1738 you can set it to @code{?\\}; then the functions that transform file names
|
|
1739 use backslashes in their output.
|
|
1740
|
|
1741 File names using backslashes work as input to Lisp primitives even on
|
|
1742 MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
|
|
1743 value of @code{?/}.
|
|
1744 @end defvar
|
|
1745 @end ignore
|
|
1746
|
|
1747 @node Relative File Names
|
|
1748 @subsection Absolute and Relative File Names
|
|
1749 @cindex absolute file name
|
|
1750 @cindex relative file name
|
|
1751
|
|
1752 All the directories in the file system form a tree starting at the
|
|
1753 root directory. A file name can specify all the directory names
|
|
1754 starting from the root of the tree; then it is called an @dfn{absolute}
|
|
1755 file name. Or it can specify the position of the file in the tree
|
|
1756 relative to a default directory; then it is called a @dfn{relative} file
|
|
1757 name. On Unix and GNU/Linux, an absolute file name starts with a slash
|
|
1758 or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
|
|
1759 MS-Windows, an absolute file name starts with a slash or a backslash, or
|
|
1760 with a drive specification @samp{@var{x}:/}, where @var{x} is the
|
|
1761 @dfn{drive letter}. The rules on VMS are complicated.
|
|
1762
|
|
1763 @defun file-name-absolute-p filename
|
|
1764 This function returns @code{t} if file @var{filename} is an absolute
|
|
1765 file name, @code{nil} otherwise. On VMS, this function understands both
|
|
1766 Unix syntax and VMS syntax.
|
|
1767
|
|
1768 @example
|
|
1769 @group
|
|
1770 (file-name-absolute-p "~rms/foo")
|
|
1771 @result{} t
|
|
1772 @end group
|
|
1773 @group
|
|
1774 (file-name-absolute-p "rms/foo")
|
|
1775 @result{} nil
|
|
1776 @end group
|
|
1777 @group
|
|
1778 (file-name-absolute-p "/user/rms/foo")
|
|
1779 @result{} t
|
|
1780 @end group
|
|
1781 @end example
|
|
1782 @end defun
|
|
1783
|
|
1784 Given a possibly relative file name, you can convert it to an
|
|
1785 absolute name using @code{expand-file-name} (@pxref{File Name
|
|
1786 Expansion}). This function converts absolute file names to relative
|
|
1787 names:
|
|
1788
|
|
1789 @defun file-relative-name filename &optional directory
|
|
1790 This function tries to return a relative name that is equivalent to
|
|
1791 @var{filename}, assuming the result will be interpreted relative to
|
|
1792 @var{directory} (an absolute directory name or directory file name).
|
|
1793 If @var{directory} is omitted or @code{nil}, it defaults to the
|
|
1794 current buffer's default directory.
|
|
1795
|
|
1796 On some operating systems, an absolute file name begins with a device
|
|
1797 name. On such systems, @var{filename} has no relative equivalent based
|
|
1798 on @var{directory} if they start with two different device names. In
|
|
1799 this case, @code{file-relative-name} returns @var{filename} in absolute
|
|
1800 form.
|
|
1801
|
|
1802 @example
|
|
1803 (file-relative-name "/foo/bar" "/foo/")
|
|
1804 @result{} "bar"
|
|
1805 (file-relative-name "/foo/bar" "/hack/")
|
|
1806 @result{} "../foo/bar"
|
|
1807 @end example
|
|
1808 @end defun
|
|
1809
|
|
1810 @node Directory Names
|
|
1811 @comment node-name, next, previous, up
|
|
1812 @subsection Directory Names
|
|
1813 @cindex directory name
|
|
1814 @cindex file name of directory
|
|
1815
|
|
1816 A @dfn{directory name} is the name of a directory. A directory is
|
|
1817 actually a kind of file, so it has a file name, which is related to
|
|
1818 the directory name but not identical to it. (This is not quite the
|
|
1819 same as the usual Unix terminology.) These two different names for
|
|
1820 the same entity are related by a syntactic transformation. On GNU and
|
|
1821 Unix systems, this is simple: a directory name ends in a slash,
|
|
1822 whereas the directory's name as a file lacks that slash. On MS-DOS and
|
|
1823 VMS, the relationship is more complicated.
|
|
1824
|
|
1825 The difference between a directory name and its name as a file is
|
|
1826 subtle but crucial. When an Emacs variable or function argument is
|
|
1827 described as being a directory name, a file name of a directory is not
|
|
1828 acceptable. When @code{file-name-directory} returns a string, that is
|
|
1829 always a directory name.
|
|
1830
|
|
1831 The following two functions convert between directory names and file
|
|
1832 names. They do nothing special with environment variable substitutions
|
|
1833 such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
|
|
1834
|
|
1835 @defun file-name-as-directory filename
|
|
1836 This function returns a string representing @var{filename} in a form
|
|
1837 that the operating system will interpret as the name of a directory. On
|
|
1838 most systems, this means appending a slash to the string (if it does not
|
|
1839 already end in one). On VMS, the function converts a string of the form
|
|
1840 @file{[X]Y.DIR.1} to the form @file{[X.Y]}.
|
|
1841
|
|
1842 @example
|
|
1843 @group
|
|
1844 (file-name-as-directory "~rms/lewis")
|
|
1845 @result{} "~rms/lewis/"
|
|
1846 @end group
|
|
1847 @end example
|
|
1848 @end defun
|
|
1849
|
|
1850 @defun directory-file-name dirname
|
|
1851 This function returns a string representing @var{dirname} in a form that
|
|
1852 the operating system will interpret as the name of a file. On most
|
|
1853 systems, this means removing the final slash (or backslash) from the
|
|
1854 string. On VMS, the function converts a string of the form @file{[X.Y]}
|
|
1855 to @file{[X]Y.DIR.1}.
|
|
1856
|
|
1857 @example
|
|
1858 @group
|
|
1859 (directory-file-name "~lewis/")
|
|
1860 @result{} "~lewis"
|
|
1861 @end group
|
|
1862 @end example
|
|
1863 @end defun
|
|
1864
|
|
1865 Given a directory name, you can combine it with a relative file name
|
|
1866 using @code{concat}:
|
|
1867
|
|
1868 @example
|
|
1869 (concat @var{dirname} @var{relfile})
|
|
1870 @end example
|
|
1871
|
|
1872 @noindent
|
|
1873 Be sure to verify that the file name is relative before doing that.
|
|
1874 If you use an absolute file name, the results could be syntactically
|
|
1875 invalid or refer to the wrong file.
|
|
1876
|
|
1877 If you want to use a directory file name in making such a
|
|
1878 combination, you must first convert it to a directory name using
|
|
1879 @code{file-name-as-directory}:
|
|
1880
|
|
1881 @example
|
|
1882 (concat (file-name-as-directory @var{dirfile}) @var{relfile})
|
|
1883 @end example
|
|
1884
|
|
1885 @noindent
|
|
1886 Don't try concatenating a slash by hand, as in
|
|
1887
|
|
1888 @example
|
|
1889 ;;; @r{Wrong!}
|
|
1890 (concat @var{dirfile} "/" @var{relfile})
|
|
1891 @end example
|
|
1892
|
|
1893 @noindent
|
|
1894 because this is not portable. Always use
|
|
1895 @code{file-name-as-directory}.
|
|
1896
|
|
1897 @cindex directory name abbreviation
|
|
1898 Directory name abbreviations are useful for directories that are
|
|
1899 normally accessed through symbolic links. Sometimes the users recognize
|
|
1900 primarily the link's name as ``the name'' of the directory, and find it
|
|
1901 annoying to see the directory's ``real'' name. If you define the link
|
|
1902 name as an abbreviation for the ``real'' name, Emacs shows users the
|
|
1903 abbreviation instead.
|
|
1904
|
|
1905 @defvar directory-abbrev-alist
|
|
1906 The variable @code{directory-abbrev-alist} contains an alist of
|
|
1907 abbreviations to use for file directories. Each element has the form
|
|
1908 @code{(@var{from} . @var{to})}, and says to replace @var{from} with
|
|
1909 @var{to} when it appears in a directory name. The @var{from} string is
|
|
1910 actually a regular expression; it should always start with @samp{^}.
|
|
1911 The @var{to} string should be an ordinary absolute directory name. Do
|
|
1912 not use @samp{~} to stand for a home directory in that string. The
|
|
1913 function @code{abbreviate-file-name} performs these substitutions.
|
|
1914
|
|
1915 You can set this variable in @file{site-init.el} to describe the
|
|
1916 abbreviations appropriate for your site.
|
|
1917
|
|
1918 Here's an example, from a system on which file system @file{/home/fsf}
|
|
1919 and so on are normally accessed through symbolic links named @file{/fsf}
|
|
1920 and so on.
|
|
1921
|
|
1922 @example
|
|
1923 (("^/home/fsf" . "/fsf")
|
|
1924 ("^/home/gp" . "/gp")
|
|
1925 ("^/home/gd" . "/gd"))
|
|
1926 @end example
|
|
1927 @end defvar
|
|
1928
|
|
1929 To convert a directory name to its abbreviation, use this
|
|
1930 function:
|
|
1931
|
|
1932 @defun abbreviate-file-name filename
|
|
1933 @anchor{Definition of abbreviate-file-name}
|
|
1934 This function applies abbreviations from @code{directory-abbrev-alist}
|
|
1935 to its argument, and substitutes @samp{~} for the user's home
|
|
1936 directory. You can use it for directory names and for file names,
|
|
1937 because it recognizes abbreviations even as part of the name.
|
|
1938 @end defun
|
|
1939
|
|
1940 @node File Name Expansion
|
|
1941 @subsection Functions that Expand Filenames
|
|
1942 @cindex expansion of file names
|
|
1943
|
|
1944 @dfn{Expansion} of a file name means converting a relative file name
|
|
1945 to an absolute one. Since this is done relative to a default directory,
|
|
1946 you must specify the default directory name as well as the file name to
|
|
1947 be expanded. Expansion also simplifies file names by eliminating
|
|
1948 redundancies such as @file{./} and @file{@var{name}/../}.
|
|
1949
|
|
1950 @defun expand-file-name filename &optional directory
|
|
1951 This function converts @var{filename} to an absolute file name. If
|
|
1952 @var{directory} is supplied, it is the default directory to start with
|
|
1953 if @var{filename} is relative. (The value of @var{directory} should
|
|
1954 itself be an absolute directory name or directory file name; it may
|
|
1955 start with @samp{~}.) Otherwise, the current buffer's value of
|
|
1956 @code{default-directory} is used. For example:
|
|
1957
|
|
1958 @example
|
|
1959 @group
|
|
1960 (expand-file-name "foo")
|
|
1961 @result{} "/xcssun/users/rms/lewis/foo"
|
|
1962 @end group
|
|
1963 @group
|
|
1964 (expand-file-name "../foo")
|
|
1965 @result{} "/xcssun/users/rms/foo"
|
|
1966 @end group
|
|
1967 @group
|
|
1968 (expand-file-name "foo" "/usr/spool/")
|
|
1969 @result{} "/usr/spool/foo"
|
|
1970 @end group
|
|
1971 @group
|
|
1972 (expand-file-name "$HOME/foo")
|
|
1973 @result{} "/xcssun/users/rms/lewis/$HOME/foo"
|
|
1974 @end group
|
|
1975 @end example
|
|
1976
|
|
1977 If the part of the combined file name before the first slash is
|
|
1978 @samp{~}, it expands to the value of the @env{HOME} environment
|
|
1979 variable (usually your home directory). If the part before the first
|
|
1980 slash is @samp{~@var{user}} and if @var{user} is a valid login name,
|
|
1981 it expands to @var{user}'s home directory.
|
|
1982
|
|
1983 Filenames containing @samp{.} or @samp{..} are simplified to their
|
|
1984 canonical form:
|
|
1985
|
|
1986 @example
|
|
1987 @group
|
|
1988 (expand-file-name "bar/../foo")
|
|
1989 @result{} "/xcssun/users/rms/lewis/foo"
|
|
1990 @end group
|
|
1991 @end example
|
|
1992
|
|
1993 In some cases, a leading @samp{..} component can remain in the output:
|
|
1994
|
|
1995 @example
|
|
1996 @group
|
|
1997 (expand-file-name "../home" "/")
|
|
1998 @result{} "/../home"
|
|
1999 @end group
|
|
2000 @end example
|
|
2001
|
|
2002 @noindent
|
|
2003 This is for the sake of filesystems that have the concept of a
|
|
2004 ``superroot'' above the root directory @file{/}. On other filesystems,
|
|
2005 @file{/../} is interpreted exactly the same as @file{/}.
|
|
2006
|
|
2007 Note that @code{expand-file-name} does @emph{not} expand environment
|
|
2008 variables; only @code{substitute-in-file-name} does that.
|
|
2009
|
|
2010 Note also that @code{expand-file-name} does not follow symbolic links
|
|
2011 at any level. This results in a difference between the way
|
|
2012 @code{file-truename} and @code{expand-file-name} treat @samp{..}.
|
|
2013 Assuming that @samp{/tmp/bar} is a symbolic link to the directory
|
|
2014 @samp{/tmp/foo/bar} we get:
|
|
2015
|
|
2016 @example
|
|
2017 @group
|
|
2018 (file-truename "/tmp/bar/../myfile")
|
|
2019 @result{} "/tmp/foo/myfile"
|
|
2020 @end group
|
|
2021 @group
|
|
2022 (expand-file-name "/tmp/bar/../myfile")
|
|
2023 @result{} "/tmp/myfile"
|
|
2024 @end group
|
|
2025 @end example
|
|
2026
|
|
2027 If you may need to follow symbolic links preceding @samp{..}, you
|
|
2028 should make sure to call @code{file-truename} without prior direct or
|
|
2029 indirect calls to @code{expand-file-name}. @xref{Truenames}.
|
|
2030 @end defun
|
|
2031
|
|
2032 @defvar default-directory
|
|
2033 The value of this buffer-local variable is the default directory for the
|
|
2034 current buffer. It should be an absolute directory name; it may start
|
|
2035 with @samp{~}. This variable is buffer-local in every buffer.
|
|
2036
|
|
2037 @code{expand-file-name} uses the default directory when its second
|
|
2038 argument is @code{nil}.
|
|
2039
|
|
2040 Aside from VMS, the value is always a string ending with a slash.
|
|
2041
|
|
2042 @example
|
|
2043 @group
|
|
2044 default-directory
|
|
2045 @result{} "/user/lewis/manual/"
|
|
2046 @end group
|
|
2047 @end example
|
|
2048 @end defvar
|
|
2049
|
|
2050 @defun substitute-in-file-name filename
|
|
2051 @anchor{Definition of substitute-in-file-name}
|
|
2052 This function replaces environment variable references in
|
|
2053 @var{filename} with the environment variable values. Following
|
|
2054 standard Unix shell syntax, @samp{$} is the prefix to substitute an
|
|
2055 environment variable value. If the input contains @samp{$$}, that is
|
|
2056 converted to @samp{$}; this gives the user a way to ``quote'' a
|
|
2057 @samp{$}.
|
|
2058
|
|
2059 The environment variable name is the series of alphanumeric characters
|
|
2060 (including underscores) that follow the @samp{$}. If the character following
|
|
2061 the @samp{$} is a @samp{@{}, then the variable name is everything up to the
|
|
2062 matching @samp{@}}.
|
|
2063
|
|
2064 Calling @code{substitute-in-file-name} on output produced by
|
|
2065 @code{substitute-in-file-name} tends to give incorrect results. For
|
|
2066 instance, use of @samp{$$} to quote a single @samp{$} won't work
|
|
2067 properly, and @samp{$} in an environment variable's value could lead
|
|
2068 to repeated substitution. Therefore, programs that call this function
|
|
2069 and put the output where it will be passed to this function need to
|
|
2070 double all @samp{$} characters to prevent subsequent incorrect
|
|
2071 results.
|
|
2072
|
|
2073 @c Wordy to avoid overfull hbox. --rjc 15mar92
|
|
2074 Here we assume that the environment variable @code{HOME}, which holds
|
|
2075 the user's home directory name, has value @samp{/xcssun/users/rms}.
|
|
2076
|
|
2077 @example
|
|
2078 @group
|
|
2079 (substitute-in-file-name "$HOME/foo")
|
|
2080 @result{} "/xcssun/users/rms/foo"
|
|
2081 @end group
|
|
2082 @end example
|
|
2083
|
|
2084 After substitution, if a @samp{~} or a @samp{/} appears immediately
|
|
2085 after another @samp{/}, the function discards everything before it (up
|
|
2086 through the immediately preceding @samp{/}).
|
|
2087
|
|
2088 @example
|
|
2089 @group
|
|
2090 (substitute-in-file-name "bar/~/foo")
|
|
2091 @result{} "~/foo"
|
|
2092 @end group
|
|
2093 @group
|
|
2094 (substitute-in-file-name "/usr/local/$HOME/foo")
|
|
2095 @result{} "/xcssun/users/rms/foo"
|
|
2096 ;; @r{@file{/usr/local/} has been discarded.}
|
|
2097 @end group
|
|
2098 @end example
|
|
2099
|
|
2100 On VMS, @samp{$} substitution is not done, so this function does nothing
|
|
2101 on VMS except discard superfluous initial components as shown above.
|
|
2102 @end defun
|
|
2103
|
|
2104 @node Unique File Names
|
|
2105 @subsection Generating Unique File Names
|
|
2106
|
|
2107 Some programs need to write temporary files. Here is the usual way to
|
|
2108 construct a name for such a file:
|
|
2109
|
|
2110 @example
|
|
2111 (make-temp-file @var{name-of-application})
|
|
2112 @end example
|
|
2113
|
|
2114 @noindent
|
|
2115 The job of @code{make-temp-file} is to prevent two different users or
|
|
2116 two different jobs from trying to use the exact same file name.
|
|
2117
|
|
2118 @defun make-temp-file prefix &optional dir-flag suffix
|
|
2119 This function creates a temporary file and returns its name. Emacs
|
|
2120 creates the temporary file's name by adding to @var{prefix} some
|
|
2121 random characters that are different in each Emacs job. The result is
|
|
2122 guaranteed to be a newly created empty file. On MS-DOS, this function
|
|
2123 can truncate the @var{string} prefix to fit into the 8+3 file-name
|
|
2124 limits. If @var{prefix} is a relative file name, it is expanded
|
|
2125 against @code{temporary-file-directory}.
|
|
2126
|
|
2127 @example
|
|
2128 @group
|
|
2129 (make-temp-file "foo")
|
|
2130 @result{} "/tmp/foo232J6v"
|
|
2131 @end group
|
|
2132 @end example
|
|
2133
|
|
2134 When @code{make-temp-file} returns, the file has been created and is
|
|
2135 empty. At that point, you should write the intended contents into the
|
|
2136 file.
|
|
2137
|
|
2138 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
|
|
2139 empty directory instead of an empty file. It returns the file name,
|
|
2140 not the directory name, of that directory. @xref{Directory Names}.
|
|
2141
|
|
2142 If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
|
|
2143 the end of the file name.
|
|
2144
|
|
2145 To prevent conflicts among different libraries running in the same
|
|
2146 Emacs, each Lisp program that uses @code{make-temp-file} should have its
|
|
2147 own @var{prefix}. The number added to the end of @var{prefix}
|
|
2148 distinguishes between the same application running in different Emacs
|
|
2149 jobs. Additional added characters permit a large number of distinct
|
|
2150 names even in one Emacs job.
|
|
2151 @end defun
|
|
2152
|
|
2153 The default directory for temporary files is controlled by the
|
|
2154 variable @code{temporary-file-directory}. This variable gives the user
|
|
2155 a uniform way to specify the directory for all temporary files. Some
|
|
2156 programs use @code{small-temporary-file-directory} instead, if that is
|
|
2157 non-@code{nil}. To use it, you should expand the prefix against
|
|
2158 the proper directory before calling @code{make-temp-file}.
|
|
2159
|
|
2160 In older Emacs versions where @code{make-temp-file} does not exist,
|
|
2161 you should use @code{make-temp-name} instead:
|
|
2162
|
|
2163 @example
|
|
2164 (make-temp-name
|
|
2165 (expand-file-name @var{name-of-application}
|
|
2166 temporary-file-directory))
|
|
2167 @end example
|
|
2168
|
|
2169 @defun make-temp-name string
|
|
2170 This function generates a string that can be used as a unique file
|
|
2171 name. The name starts with @var{string}, and has several random
|
|
2172 characters appended to it, which are different in each Emacs job. It
|
|
2173 is like @code{make-temp-file} except that it just constructs a name,
|
|
2174 and does not create a file. Another difference is that @var{string}
|
|
2175 should be an absolute file name. On MS-DOS, this function can
|
|
2176 truncate the @var{string} prefix to fit into the 8+3 file-name limits.
|
|
2177 @end defun
|
|
2178
|
|
2179 @defvar temporary-file-directory
|
|
2180 @cindex @code{TMPDIR} environment variable
|
|
2181 @cindex @code{TMP} environment variable
|
|
2182 @cindex @code{TEMP} environment variable
|
|
2183 This variable specifies the directory name for creating temporary files.
|
|
2184 Its value should be a directory name (@pxref{Directory Names}), but it
|
|
2185 is good for Lisp programs to cope if the value is a directory's file
|
|
2186 name instead. Using the value as the second argument to
|
|
2187 @code{expand-file-name} is a good way to achieve that.
|
|
2188
|
|
2189 The default value is determined in a reasonable way for your operating
|
|
2190 system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
|
|
2191 environment variables, with a fall-back to a system-dependent name if
|
|
2192 none of these variables is defined.
|
|
2193
|
|
2194 Even if you do not use @code{make-temp-file} to create the temporary
|
|
2195 file, you should still use this variable to decide which directory to
|
|
2196 put the file in. However, if you expect the file to be small, you
|
|
2197 should use @code{small-temporary-file-directory} first if that is
|
|
2198 non-@code{nil}.
|
|
2199 @end defvar
|
|
2200
|
|
2201 @defvar small-temporary-file-directory
|
|
2202 This variable specifies the directory name for
|
|
2203 creating certain temporary files, which are likely to be small.
|
|
2204
|
|
2205 If you want to write a temporary file which is likely to be small, you
|
|
2206 should compute the directory like this:
|
|
2207
|
|
2208 @example
|
|
2209 (make-temp-file
|
|
2210 (expand-file-name @var{prefix}
|
|
2211 (or small-temporary-file-directory
|
|
2212 temporary-file-directory)))
|
|
2213 @end example
|
|
2214 @end defvar
|
|
2215
|
|
2216 @node File Name Completion
|
|
2217 @subsection File Name Completion
|
|
2218 @cindex file name completion subroutines
|
|
2219 @cindex completion, file name
|
|
2220
|
|
2221 This section describes low-level subroutines for completing a file
|
|
2222 name. For higher level functions, see @ref{Reading File Names}.
|
|
2223
|
|
2224 @defun file-name-all-completions partial-filename directory
|
|
2225 This function returns a list of all possible completions for a file
|
|
2226 whose name starts with @var{partial-filename} in directory
|
|
2227 @var{directory}. The order of the completions is the order of the files
|
|
2228 in the directory, which is unpredictable and conveys no useful
|
|
2229 information.
|
|
2230
|
|
2231 The argument @var{partial-filename} must be a file name containing no
|
|
2232 directory part and no slash (or backslash on some systems). The current
|
|
2233 buffer's default directory is prepended to @var{directory}, if
|
|
2234 @var{directory} is not absolute.
|
|
2235
|
|
2236 In the following example, suppose that @file{~rms/lewis} is the current
|
|
2237 default directory, and has five files whose names begin with @samp{f}:
|
|
2238 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
|
|
2239 @file{file.c.~2~}.@refill
|
|
2240
|
|
2241 @example
|
|
2242 @group
|
|
2243 (file-name-all-completions "f" "")
|
|
2244 @result{} ("foo" "file~" "file.c.~2~"
|
|
2245 "file.c.~1~" "file.c")
|
|
2246 @end group
|
|
2247
|
|
2248 @group
|
|
2249 (file-name-all-completions "fo" "")
|
|
2250 @result{} ("foo")
|
|
2251 @end group
|
|
2252 @end example
|
|
2253 @end defun
|
|
2254
|
|
2255 @defun file-name-completion filename directory &optional predicate
|
|
2256 This function completes the file name @var{filename} in directory
|
|
2257 @var{directory}. It returns the longest prefix common to all file names
|
|
2258 in directory @var{directory} that start with @var{filename}. If
|
|
2259 @var{predicate} is non-@code{nil} then it ignores possible completions
|
|
2260 that don't satisfy @var{predicate}, after calling that function
|
|
2261 with one argument, the expanded absolute file name.
|
|
2262
|
|
2263 If only one match exists and @var{filename} matches it exactly, the
|
|
2264 function returns @code{t}. The function returns @code{nil} if directory
|
|
2265 @var{directory} contains no name starting with @var{filename}.
|
|
2266
|
|
2267 In the following example, suppose that the current default directory
|
|
2268 has five files whose names begin with @samp{f}: @file{foo},
|
|
2269 @file{file~}, @file{file.c}, @file{file.c.~1~}, and
|
|
2270 @file{file.c.~2~}.@refill
|
|
2271
|
|
2272 @example
|
|
2273 @group
|
|
2274 (file-name-completion "fi" "")
|
|
2275 @result{} "file"
|
|
2276 @end group
|
|
2277
|
|
2278 @group
|
|
2279 (file-name-completion "file.c.~1" "")
|
|
2280 @result{} "file.c.~1~"
|
|
2281 @end group
|
|
2282
|
|
2283 @group
|
|
2284 (file-name-completion "file.c.~1~" "")
|
|
2285 @result{} t
|
|
2286 @end group
|
|
2287
|
|
2288 @group
|
|
2289 (file-name-completion "file.c.~3" "")
|
|
2290 @result{} nil
|
|
2291 @end group
|
|
2292 @end example
|
|
2293 @end defun
|
|
2294
|
|
2295 @defopt completion-ignored-extensions
|
|
2296 @code{file-name-completion} usually ignores file names that end in any
|
|
2297 string in this list. It does not ignore them when all the possible
|
|
2298 completions end in one of these suffixes. This variable has no effect
|
|
2299 on @code{file-name-all-completions}.@refill
|
|
2300
|
|
2301 A typical value might look like this:
|
|
2302
|
|
2303 @example
|
|
2304 @group
|
|
2305 completion-ignored-extensions
|
|
2306 @result{} (".o" ".elc" "~" ".dvi")
|
|
2307 @end group
|
|
2308 @end example
|
|
2309
|
|
2310 If an element of @code{completion-ignored-extensions} ends in a slash
|
|
2311 @samp{/}, it signals a directory. The elements which do @emph{not} end
|
|
2312 in a slash will never match a directory; thus, the above value will not
|
|
2313 filter out a directory named @file{foo.elc}.
|
|
2314 @end defopt
|
|
2315
|
|
2316 @node Standard File Names
|
|
2317 @subsection Standard File Names
|
|
2318
|
|
2319 Most of the file names used in Lisp programs are entered by the user.
|
|
2320 But occasionally a Lisp program needs to specify a standard file name
|
|
2321 for a particular use---typically, to hold customization information
|
|
2322 about each user. For example, abbrev definitions are stored (by
|
|
2323 default) in the file @file{~/.abbrev_defs}; the @code{completion}
|
|
2324 package stores completions in the file @file{~/.completions}. These are
|
|
2325 two of the many standard file names used by parts of Emacs for certain
|
|
2326 purposes.
|
|
2327
|
|
2328 Various operating systems have their own conventions for valid file
|
|
2329 names and for which file names to use for user profile data. A Lisp
|
|
2330 program which reads a file using a standard file name ought to use, on
|
|
2331 each type of system, a file name suitable for that system. The function
|
|
2332 @code{convert-standard-filename} makes this easy to do.
|
|
2333
|
|
2334 @defun convert-standard-filename filename
|
|
2335 This function alters the file name @var{filename} to fit the conventions
|
|
2336 of the operating system in use, and returns the result as a new string.
|
|
2337 @end defun
|
|
2338
|
|
2339 The recommended way to specify a standard file name in a Lisp program
|
|
2340 is to choose a name which fits the conventions of GNU and Unix systems,
|
|
2341 usually with a nondirectory part that starts with a period, and pass it
|
|
2342 to @code{convert-standard-filename} instead of using it directly. Here
|
|
2343 is an example from the @code{completion} package:
|
|
2344
|
|
2345 @example
|
|
2346 (defvar save-completions-file-name
|
|
2347 (convert-standard-filename "~/.completions")
|
|
2348 "*The file name to save completions to.")
|
|
2349 @end example
|
|
2350
|
|
2351 On GNU and Unix systems, and on some other systems as well,
|
|
2352 @code{convert-standard-filename} returns its argument unchanged. On
|
|
2353 some other systems, it alters the name to fit the system's conventions.
|
|
2354
|
|
2355 For example, on MS-DOS the alterations made by this function include
|
|
2356 converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the
|
|
2357 middle of the name to @samp{.} if there is no other @samp{.}, inserting
|
|
2358 a @samp{.} after eight characters if there is none, and truncating to
|
|
2359 three characters after the @samp{.}. (It makes other changes as well.)
|
|
2360 Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
|
|
2361 @file{.completions} becomes @file{_complet.ion}.
|
|
2362
|
|
2363 @node Contents of Directories
|
|
2364 @section Contents of Directories
|
|
2365 @cindex directory-oriented functions
|
|
2366 @cindex file names in directory
|
|
2367
|
|
2368 A directory is a kind of file that contains other files entered under
|
|
2369 various names. Directories are a feature of the file system.
|
|
2370
|
|
2371 Emacs can list the names of the files in a directory as a Lisp list,
|
|
2372 or display the names in a buffer using the @code{ls} shell command. In
|
|
2373 the latter case, it can optionally display information about each file,
|
|
2374 depending on the options passed to the @code{ls} command.
|
|
2375
|
|
2376 @defun directory-files directory &optional full-name match-regexp nosort
|
|
2377 This function returns a list of the names of the files in the directory
|
|
2378 @var{directory}. By default, the list is in alphabetical order.
|
|
2379
|
|
2380 If @var{full-name} is non-@code{nil}, the function returns the files'
|
|
2381 absolute file names. Otherwise, it returns the names relative to
|
|
2382 the specified directory.
|
|
2383
|
|
2384 If @var{match-regexp} is non-@code{nil}, this function returns only
|
|
2385 those file names that contain a match for that regular expression---the
|
|
2386 other file names are excluded from the list. On case-insensitive
|
|
2387 filesystems, the regular expression matching is case-insensitive.
|
|
2388
|
|
2389 @c Emacs 19 feature
|
|
2390 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
|
|
2391 the list, so you get the file names in no particular order. Use this if
|
|
2392 you want the utmost possible speed and don't care what order the files
|
|
2393 are processed in. If the order of processing is visible to the user,
|
|
2394 then the user will probably be happier if you do sort the names.
|
|
2395
|
|
2396 @example
|
|
2397 @group
|
|
2398 (directory-files "~lewis")
|
|
2399 @result{} ("#foo#" "#foo.el#" "." ".."
|
|
2400 "dired-mods.el" "files.texi"
|
|
2401 "files.texi.~1~")
|
|
2402 @end group
|
|
2403 @end example
|
|
2404
|
|
2405 An error is signaled if @var{directory} is not the name of a directory
|
|
2406 that can be read.
|
|
2407 @end defun
|
|
2408
|
|
2409 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
|
|
2410 This is similar to @code{directory-files} in deciding which files
|
|
2411 to report on and how to report their names. However, instead
|
|
2412 of returning a list of file names, it returns for each file a
|
|
2413 list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
|
|
2414 is what @code{file-attributes} would return for that file.
|
|
2415 The optional argument @var{id-format} has the same meaning as the
|
|
2416 corresponding argument to @code{file-attributes} (@pxref{Definition
|
|
2417 of file-attributes}).
|
|
2418 @end defun
|
|
2419
|
|
2420 @defun file-name-all-versions file dirname
|
|
2421 This function returns a list of all versions of the file named
|
|
2422 @var{file} in directory @var{dirname}. It is only available on VMS.
|
|
2423 @end defun
|
|
2424
|
|
2425 @defun file-expand-wildcards pattern &optional full
|
|
2426 This function expands the wildcard pattern @var{pattern}, returning
|
|
2427 a list of file names that match it.
|
|
2428
|
|
2429 If @var{pattern} is written as an absolute file name,
|
|
2430 the values are absolute also.
|
|
2431
|
|
2432 If @var{pattern} is written as a relative file name, it is interpreted
|
|
2433 relative to the current default directory. The file names returned are
|
|
2434 normally also relative to the current default directory. However, if
|
|
2435 @var{full} is non-@code{nil}, they are absolute.
|
|
2436 @end defun
|
|
2437
|
|
2438 @defun insert-directory file switches &optional wildcard full-directory-p
|
|
2439 This function inserts (in the current buffer) a directory listing for
|
|
2440 directory @var{file}, formatted with @code{ls} according to
|
|
2441 @var{switches}. It leaves point after the inserted text.
|
|
2442 @var{switches} may be a string of options, or a list of strings
|
|
2443 representing individual options.
|
|
2444
|
|
2445 The argument @var{file} may be either a directory name or a file
|
|
2446 specification including wildcard characters. If @var{wildcard} is
|
|
2447 non-@code{nil}, that means treat @var{file} as a file specification with
|
|
2448 wildcards.
|
|
2449
|
|
2450 If @var{full-directory-p} is non-@code{nil}, that means the directory
|
|
2451 listing is expected to show the full contents of a directory. You
|
|
2452 should specify @code{t} when @var{file} is a directory and switches do
|
|
2453 not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to
|
|
2454 describe a directory itself as a file, rather than showing its
|
|
2455 contents.)
|
|
2456
|
|
2457 On most systems, this function works by running a directory listing
|
|
2458 program whose name is in the variable @code{insert-directory-program}.
|
|
2459 If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
|
|
2460 @code{shell-file-name}, to expand the wildcards.
|
|
2461
|
|
2462 MS-DOS and MS-Windows systems usually lack the standard Unix program
|
|
2463 @code{ls}, so this function emulates the standard Unix program @code{ls}
|
|
2464 with Lisp code.
|
|
2465
|
|
2466 As a technical detail, when @var{switches} contains the long
|
|
2467 @samp{--dired} option, @code{insert-directory} treats it specially,
|
|
2468 for the sake of dired. However, the normally equivalent short
|
|
2469 @samp{-D} option is just passed on to @code{insert-directory-program},
|
|
2470 as any other option.
|
|
2471 @end defun
|
|
2472
|
|
2473 @defvar insert-directory-program
|
|
2474 This variable's value is the program to run to generate a directory listing
|
|
2475 for the function @code{insert-directory}. It is ignored on systems
|
|
2476 which generate the listing with Lisp code.
|
|
2477 @end defvar
|
|
2478
|
|
2479 @node Create/Delete Dirs
|
|
2480 @section Creating and Deleting Directories
|
|
2481 @cindex creating and deleting directories
|
|
2482 @c Emacs 19 features
|
|
2483
|
|
2484 Most Emacs Lisp file-manipulation functions get errors when used on
|
|
2485 files that are directories. For example, you cannot delete a directory
|
|
2486 with @code{delete-file}. These special functions exist to create and
|
|
2487 delete directories.
|
|
2488
|
|
2489 @defun make-directory dirname &optional parents
|
|
2490 This function creates a directory named @var{dirname}.
|
|
2491 If @var{parents} is non-@code{nil}, as is always the case in an
|
|
2492 interactive call, that means to create the parent directories first,
|
|
2493 if they don't already exist.
|
|
2494 @end defun
|
|
2495
|
|
2496 @defun delete-directory dirname
|
|
2497 This function deletes the directory named @var{dirname}. The function
|
|
2498 @code{delete-file} does not work for files that are directories; you
|
|
2499 must use @code{delete-directory} for them. If the directory contains
|
|
2500 any files, @code{delete-directory} signals an error.
|
|
2501
|
|
2502 This function only follows symbolic links at the level of parent
|
|
2503 directories.
|
|
2504 @end defun
|
|
2505
|
|
2506 @node Magic File Names
|
|
2507 @section Making Certain File Names ``Magic''
|
|
2508 @cindex magic file names
|
|
2509
|
|
2510 @c Emacs 19 feature
|
|
2511 You can implement special handling for certain file names. This is
|
|
2512 called making those names @dfn{magic}. The principal use for this
|
|
2513 feature is in implementing remote file names (@pxref{Remote Files,,
|
|
2514 Remote Files, emacs, The GNU Emacs Manual}).
|
|
2515
|
|
2516 To define a kind of magic file name, you must supply a regular
|
|
2517 expression to define the class of names (all those that match the
|
|
2518 regular expression), plus a handler that implements all the primitive
|
|
2519 Emacs file operations for file names that do match.
|
|
2520
|
|
2521 The variable @code{file-name-handler-alist} holds a list of handlers,
|
|
2522 together with regular expressions that determine when to apply each
|
|
2523 handler. Each element has this form:
|
|
2524
|
|
2525 @example
|
|
2526 (@var{regexp} . @var{handler})
|
|
2527 @end example
|
|
2528
|
|
2529 @noindent
|
|
2530 All the Emacs primitives for file access and file name transformation
|
|
2531 check the given file name against @code{file-name-handler-alist}. If
|
|
2532 the file name matches @var{regexp}, the primitives handle that file by
|
|
2533 calling @var{handler}.
|
|
2534
|
|
2535 The first argument given to @var{handler} is the name of the
|
|
2536 primitive, as a symbol; the remaining arguments are the arguments that
|
|
2537 were passed to that primitive. (The first of these arguments is most
|
|
2538 often the file name itself.) For example, if you do this:
|
|
2539
|
|
2540 @example
|
|
2541 (file-exists-p @var{filename})
|
|
2542 @end example
|
|
2543
|
|
2544 @noindent
|
|
2545 and @var{filename} has handler @var{handler}, then @var{handler} is
|
|
2546 called like this:
|
|
2547
|
|
2548 @example
|
|
2549 (funcall @var{handler} 'file-exists-p @var{filename})
|
|
2550 @end example
|
|
2551
|
|
2552 When a function takes two or more arguments that must be file names,
|
|
2553 it checks each of those names for a handler. For example, if you do
|
|
2554 this:
|
|
2555
|
|
2556 @example
|
|
2557 (expand-file-name @var{filename} @var{dirname})
|
|
2558 @end example
|
|
2559
|
|
2560 @noindent
|
|
2561 then it checks for a handler for @var{filename} and then for a handler
|
|
2562 for @var{dirname}. In either case, the @var{handler} is called like
|
|
2563 this:
|
|
2564
|
|
2565 @example
|
|
2566 (funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
|
|
2567 @end example
|
|
2568
|
|
2569 @noindent
|
|
2570 The @var{handler} then needs to figure out whether to handle
|
|
2571 @var{filename} or @var{dirname}.
|
|
2572
|
|
2573 If the specified file name matches more than one handler, the one
|
|
2574 whose match starts last in the file name gets precedence. This rule
|
|
2575 is chosen so that handlers for jobs such as uncompression are handled
|
|
2576 first, before handlers for jobs such as remote file access.
|
|
2577
|
|
2578 Here are the operations that a magic file name handler gets to handle:
|
|
2579
|
|
2580 @ifnottex
|
|
2581 @noindent
|
|
2582 @code{access-file}, @code{add-name-to-file},
|
|
2583 @code{byte-compiler-base-file-name},@*
|
|
2584 @code{copy-file}, @code{delete-directory},
|
|
2585 @code{delete-file},
|
|
2586 @code{diff-latest-backup-file},
|
|
2587 @code{directory-file-name},
|
|
2588 @code{directory-files},
|
|
2589 @code{directory-files-and-attributes},
|
|
2590 @code{dired-compress-file}, @code{dired-uncache},@*
|
|
2591 @code{expand-file-name},
|
|
2592 @code{file-accessible-directory-p},
|
|
2593 @code{file-attributes},
|
|
2594 @code{file-directory-p},
|
|
2595 @code{file-executable-p}, @code{file-exists-p},
|
|
2596 @code{file-local-copy}, @code{file-remote-p},
|
|
2597 @code{file-modes}, @code{file-name-all-completions},
|
|
2598 @code{file-name-as-directory},
|
|
2599 @code{file-name-completion},
|
|
2600 @code{file-name-directory},
|
|
2601 @code{file-name-nondirectory},
|
|
2602 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
|
|
2603 @code{file-ownership-preserved-p},
|
|
2604 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
|
|
2605 @code{file-truename}, @code{file-writable-p},
|
|
2606 @code{find-backup-file-name},
|
|
2607 @code{find-file-noselect},@*
|
|
2608 @code{get-file-buffer},
|
|
2609 @code{insert-directory},
|
|
2610 @code{insert-file-contents},@*
|
|
2611 @code{load},
|
|
2612 @code{make-auto-save-file-name},
|
|
2613 @code{make-directory},
|
|
2614 @code{make-directory-internal},
|
|
2615 @code{make-symbolic-link},@*
|
|
2616 @code{process-file},
|
|
2617 @code{rename-file}, @code{set-file-modes}, @code{set-file-times},
|
|
2618 @code{set-visited-file-modtime}, @code{shell-command},
|
|
2619 @code{start-file-process},
|
|
2620 @code{substitute-in-file-name},@*
|
|
2621 @code{unhandled-file-name-directory},
|
|
2622 @code{vc-registered},
|
|
2623 @code{verify-visited-file-modtime},@*
|
|
2624 @code{write-region}.
|
|
2625 @end ifnottex
|
|
2626 @iftex
|
|
2627 @noindent
|
|
2628 @flushleft
|
|
2629 @code{access-file}, @code{add-name-to-file},
|
|
2630 @code{byte-com@discretionary{}{}{}piler-base-file-name},
|
|
2631 @code{copy-file}, @code{delete-directory},
|
|
2632 @code{delete-file},
|
|
2633 @code{diff-latest-backup-file},
|
|
2634 @code{directory-file-name},
|
|
2635 @code{directory-files},
|
|
2636 @code{directory-files-and-at@discretionary{}{}{}tributes},
|
|
2637 @code{dired-compress-file}, @code{dired-uncache},
|
|
2638 @code{expand-file-name},
|
|
2639 @code{file-accessible-direc@discretionary{}{}{}tory-p},
|
|
2640 @code{file-attributes},
|
|
2641 @code{file-direct@discretionary{}{}{}ory-p},
|
|
2642 @code{file-executable-p}, @code{file-exists-p},
|
|
2643 @code{file-local-copy}, @code{file-remote-p},
|
|
2644 @code{file-modes}, @code{file-name-all-completions},
|
|
2645 @code{file-name-as-directory},
|
|
2646 @code{file-name-completion},
|
|
2647 @code{file-name-directory},
|
|
2648 @code{file-name-nondirec@discretionary{}{}{}tory},
|
|
2649 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
|
|
2650 @code{file-ownership-pre@discretionary{}{}{}served-p},
|
|
2651 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
|
|
2652 @code{file-truename}, @code{file-writable-p},
|
|
2653 @code{find-backup-file-name},
|
|
2654 @code{find-file-noselect},
|
|
2655 @code{get-file-buffer},
|
|
2656 @code{insert-directory},
|
|
2657 @code{insert-file-contents},
|
|
2658 @code{load}, @code{make-direc@discretionary{}{}{}tory},
|
|
2659 @code{make-direc@discretionary{}{}{}tory-internal},
|
|
2660 @code{make-symbolic-link},
|
|
2661 @code{process-file},
|
|
2662 @code{rename-file}, @code{set-file-modes},
|
|
2663 @code{set-visited-file-modtime}, @code{shell-command},
|
|
2664 @code{start-file-process},
|
|
2665 @code{substitute-in-file-name},
|
|
2666 @code{unhandled-file-name-directory},
|
|
2667 @code{vc-regis@discretionary{}{}{}tered},
|
|
2668 @code{verify-visited-file-modtime},
|
|
2669 @code{write-region}.
|
|
2670 @end flushleft
|
|
2671 @end iftex
|
|
2672
|
|
2673 Handlers for @code{insert-file-contents} typically need to clear the
|
|
2674 buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
|
|
2675 @var{visit} argument is non-@code{nil}. This also has the effect of
|
|
2676 unlocking the buffer if it is locked.
|
|
2677
|
|
2678 The handler function must handle all of the above operations, and
|
|
2679 possibly others to be added in the future. It need not implement all
|
|
2680 these operations itself---when it has nothing special to do for a
|
|
2681 certain operation, it can reinvoke the primitive, to handle the
|
|
2682 operation ``in the usual way.'' It should always reinvoke the primitive
|
|
2683 for an operation it does not recognize. Here's one way to do this:
|
|
2684
|
|
2685 @smallexample
|
|
2686 (defun my-file-handler (operation &rest args)
|
|
2687 ;; @r{First check for the specific operations}
|
|
2688 ;; @r{that we have special handling for.}
|
|
2689 (cond ((eq operation 'insert-file-contents) @dots{})
|
|
2690 ((eq operation 'write-region) @dots{})
|
|
2691 @dots{}
|
|
2692 ;; @r{Handle any operation we don't know about.}
|
|
2693 (t (let ((inhibit-file-name-handlers
|
|
2694 (cons 'my-file-handler
|
|
2695 (and (eq inhibit-file-name-operation operation)
|
|
2696 inhibit-file-name-handlers)))
|
|
2697 (inhibit-file-name-operation operation))
|
|
2698 (apply operation args)))))
|
|
2699 @end smallexample
|
|
2700
|
|
2701 When a handler function decides to call the ordinary Emacs primitive for
|
|
2702 the operation at hand, it needs to prevent the primitive from calling
|
|
2703 the same handler once again, thus leading to an infinite recursion. The
|
|
2704 example above shows how to do this, with the variables
|
|
2705 @code{inhibit-file-name-handlers} and
|
|
2706 @code{inhibit-file-name-operation}. Be careful to use them exactly as
|
|
2707 shown above; the details are crucial for proper behavior in the case of
|
|
2708 multiple handlers, and for operations that have two file names that may
|
|
2709 each have handlers.
|
|
2710
|
|
2711 @kindex safe-magic (@r{property})
|
|
2712 Handlers that don't really do anything special for actual access to the
|
|
2713 file---such as the ones that implement completion of host names for
|
|
2714 remote file names---should have a non-@code{nil} @code{safe-magic}
|
|
2715 property. For instance, Emacs normally ``protects'' directory names
|
|
2716 it finds in @code{PATH} from becoming magic, if they look like magic
|
|
2717 file names, by prefixing them with @samp{/:}. But if the handler that
|
|
2718 would be used for them has a non-@code{nil} @code{safe-magic}
|
|
2719 property, the @samp{/:} is not added.
|
|
2720
|
|
2721 @kindex operations (@r{property})
|
|
2722 A file name handler can have an @code{operations} property to
|
|
2723 declare which operations it handles in a nontrivial way. If this
|
|
2724 property has a non-@code{nil} value, it should be a list of
|
|
2725 operations; then only those operations will call the handler. This
|
|
2726 avoids inefficiency, but its main purpose is for autoloaded handler
|
|
2727 functions, so that they won't be loaded except when they have real
|
|
2728 work to do.
|
|
2729
|
|
2730 Simply deferring all operations to the usual primitives does not
|
|
2731 work. For instance, if the file name handler applies to
|
|
2732 @code{file-exists-p}, then it must handle @code{load} itself, because
|
|
2733 the usual @code{load} code won't work properly in that case. However,
|
|
2734 if the handler uses the @code{operations} property to say it doesn't
|
|
2735 handle @code{file-exists-p}, then it need not handle @code{load}
|
|
2736 nontrivially.
|
|
2737
|
|
2738 @defvar inhibit-file-name-handlers
|
|
2739 This variable holds a list of handlers whose use is presently inhibited
|
|
2740 for a certain operation.
|
|
2741 @end defvar
|
|
2742
|
|
2743 @defvar inhibit-file-name-operation
|
|
2744 The operation for which certain handlers are presently inhibited.
|
|
2745 @end defvar
|
|
2746
|
|
2747 @defun find-file-name-handler file operation
|
|
2748 This function returns the handler function for file name @var{file},
|
|
2749 or @code{nil} if there is none. The argument @var{operation} should
|
|
2750 be the operation to be performed on the file---the value you will pass
|
|
2751 to the handler as its first argument when you call it. If
|
|
2752 @var{operation} equals @code{inhibit-file-name-operation}, or if it is
|
|
2753 not found in the @code{operations} property of the handler, this
|
|
2754 function returns @code{nil}.
|
|
2755 @end defun
|
|
2756
|
|
2757 @defun file-local-copy filename
|
|
2758 This function copies file @var{filename} to an ordinary non-magic file
|
|
2759 on the local machine, if it isn't on the local machine already. Magic
|
|
2760 file names should handle the @code{file-local-copy} operation if they
|
|
2761 refer to files on other machines. A magic file name that is used for
|
|
2762 other purposes than remote file access should not handle
|
|
2763 @code{file-local-copy}; then this function will treat the file as
|
|
2764 local.
|
|
2765
|
|
2766 If @var{filename} is local, whether magic or not, this function does
|
|
2767 nothing and returns @code{nil}. Otherwise it returns the file name
|
|
2768 of the local copy file.
|
|
2769 @end defun
|
|
2770
|
|
2771 @defun file-remote-p filename &optional identification connected
|
|
2772 This function tests whether @var{filename} is a remote file. If
|
|
2773 @var{filename} is local (not remote), the return value is @code{nil}.
|
|
2774 If @var{filename} is indeed remote, the return value is a string that
|
|
2775 identifies the remote system.
|
|
2776
|
|
2777 This identifier string can include a host name and a user name, as
|
|
2778 well as characters designating the method used to access the remote
|
|
2779 system. For example, the remote identifier string for the filename
|
|
2780 @code{/sudo::/some/file} is @code{/sudo:root@@localhost:}.
|
|
2781
|
|
2782 If @code{file-remote-p} returns the same identifier for two different
|
|
2783 filenames, that means they are stored on the same file system and can
|
|
2784 be accessed locally with respect to each other. This means, for
|
|
2785 example, that it is possible to start a remote process accessing both
|
|
2786 files at the same time. Implementors of file handlers need to ensure
|
|
2787 this principle is valid.
|
|
2788
|
|
2789 @var{identification} specifies which part of the identifier shall be
|
|
2790 returned as string. @var{identification} can be the symbol
|
|
2791 @code{method}, @code{user} or @code{host}; any other value is handled
|
|
2792 like @code{nil} and means to return the complete identifier string.
|
|
2793 In the example above, the remote @code{user} identifier string would
|
|
2794 be @code{root}.
|
|
2795
|
|
2796 If @var{connected} is non-@code{nil}, this function returns @code{nil}
|
|
2797 even if @var{filename} is remote, if Emacs has no network connection
|
|
2798 to its host. This is useful when you want to avoid the delay of
|
|
2799 making connections when they don't exist.
|
|
2800 @end defun
|
|
2801
|
|
2802 @defun unhandled-file-name-directory filename
|
|
2803 This function returns the name of a directory that is not magic. It
|
|
2804 uses the directory part of @var{filename} if that is not magic. For a
|
|
2805 magic file name, it invokes the file name handler, which therefore
|
|
2806 decides what value to return.
|
|
2807
|
|
2808 This is useful for running a subprocess; every subprocess must have a
|
|
2809 non-magic directory to serve as its current directory, and this function
|
|
2810 is a good way to come up with one.
|
|
2811 @end defun
|
|
2812
|
|
2813 @node Format Conversion
|
|
2814 @section File Format Conversion
|
|
2815
|
|
2816 @cindex file format conversion
|
|
2817 @cindex encoding file formats
|
|
2818 @cindex decoding file formats
|
|
2819 @cindex text properties in files
|
|
2820 @cindex saving text properties
|
|
2821 Emacs performs several steps to convert the data in a buffer (text,
|
|
2822 text properties, and possibly other information) to and from a
|
|
2823 representation suitable for storing into a file. This section describes
|
|
2824 the fundamental functions that perform this @dfn{format conversion},
|
|
2825 namely @code{insert-file-contents} for reading a file into a buffer,
|
|
2826 and @code{write-region} for writing a buffer into a file.
|
|
2827
|
|
2828 @menu
|
|
2829 * Overview: Format Conversion Overview. @code{insert-file-contents} and @code{write-region}
|
|
2830 * Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}.
|
|
2831 * Piecemeal: Format Conversion Piecemeal. Specifying non-paired conversion.
|
|
2832 @end menu
|
|
2833
|
|
2834 @node Format Conversion Overview
|
|
2835 @subsection Overview
|
|
2836 @noindent
|
|
2837 The function @code{insert-file-contents}:
|
|
2838
|
|
2839 @itemize
|
|
2840 @item initially, inserts bytes from the file into the buffer;
|
|
2841 @item decodes bytes to characters as appropriate;
|
|
2842 @item processes formats as defined by entries in @code{format-alist}; and
|
|
2843 @item calls functions in @code{after-insert-file-functions}.
|
|
2844 @end itemize
|
|
2845
|
|
2846 @noindent
|
|
2847 The function @code{write-region}:
|
|
2848
|
|
2849 @itemize
|
|
2850 @item initially, calls functions in @code{write-region-annotate-functions};
|
|
2851 @item processes formats as defined by entries in @code{format-alist};
|
|
2852 @item encodes characters to bytes as appropriate; and
|
|
2853 @item modifies the file with the bytes.
|
|
2854 @end itemize
|
|
2855
|
|
2856 This shows the symmetry of the lowest-level operations; reading and
|
|
2857 writing handle things in opposite order. The rest of this section
|
|
2858 describes the two facilities surrounding the three variables named
|
|
2859 above, as well as some related functions. @ref{Coding Systems}, for
|
|
2860 details on character encoding and decoding.
|
|
2861
|
|
2862 @node Format Conversion Round-Trip
|
|
2863 @subsection Round-Trip Specification
|
|
2864
|
|
2865 The most general of the two facilities is controlled by the variable
|
|
2866 @code{format-alist}, a list of @dfn{file format} specifications, which
|
|
2867 describe textual representations used in files for the data in an Emacs
|
|
2868 buffer. The descriptions for reading and writing are paired, which is
|
|
2869 why we call this ``round-trip'' specification
|
|
2870 (@pxref{Format Conversion Piecemeal}, for non-paired specification).
|
|
2871
|
|
2872 @defvar format-alist
|
|
2873 This list contains one format definition for each defined file format.
|
|
2874 Each format definition is a list of this form:
|
|
2875
|
|
2876 @example
|
|
2877 (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
|
|
2878 @end example
|
|
2879 @end defvar
|
|
2880
|
|
2881 @cindex format definition
|
|
2882 @noindent
|
|
2883 Here is what the elements in a format definition mean:
|
|
2884
|
|
2885 @table @var
|
|
2886 @item name
|
|
2887 The name of this format.
|
|
2888
|
|
2889 @item doc-string
|
|
2890 A documentation string for the format.
|
|
2891
|
|
2892 @item regexp
|
|
2893 A regular expression which is used to recognize files represented in
|
|
2894 this format.
|
|
2895
|
|
2896 @item from-fn
|
|
2897 A shell command or function to decode data in this format (to convert
|
|
2898 file data into the usual Emacs data representation).
|
|
2899
|
|
2900 A shell command is represented as a string; Emacs runs the command as a
|
|
2901 filter to perform the conversion.
|
|
2902
|
|
2903 If @var{from-fn} is a function, it is called with two arguments, @var{begin}
|
|
2904 and @var{end}, which specify the part of the buffer it should convert.
|
|
2905 It should convert the text by editing it in place. Since this can
|
|
2906 change the length of the text, @var{from-fn} should return the modified
|
|
2907 end position.
|
|
2908
|
|
2909 One responsibility of @var{from-fn} is to make sure that the beginning
|
|
2910 of the file no longer matches @var{regexp}. Otherwise it is likely to
|
|
2911 get called again.
|
|
2912
|
|
2913 @item to-fn
|
|
2914 A shell command or function to encode data in this format---that is, to
|
|
2915 convert the usual Emacs data representation into this format.
|
|
2916
|
|
2917 If @var{to-fn} is a string, it is a shell command; Emacs runs the
|
|
2918 command as a filter to perform the conversion.
|
|
2919
|
|
2920 If @var{to-fn} is a function, it is called with three arguments:
|
|
2921 @var{begin} and @var{end}, which specify the part of the buffer it
|
|
2922 should convert, and @var{buffer}, which specifies which buffer. There
|
|
2923 are two ways it can do the conversion:
|
|
2924
|
|
2925 @itemize @bullet
|
|
2926 @item
|
|
2927 By editing the buffer in place. In this case, @var{to-fn} should
|
|
2928 return the end-position of the range of text, as modified.
|
|
2929
|
|
2930 @item
|
|
2931 By returning a list of annotations. This is a list of elements of the
|
|
2932 form @code{(@var{position} . @var{string})}, where @var{position} is an
|
|
2933 integer specifying the relative position in the text to be written, and
|
|
2934 @var{string} is the annotation to add there. The list must be sorted in
|
|
2935 order of position when @var{to-fn} returns it.
|
|
2936
|
|
2937 When @code{write-region} actually writes the text from the buffer to the
|
|
2938 file, it intermixes the specified annotations at the corresponding
|
|
2939 positions. All this takes place without modifying the buffer.
|
|
2940 @end itemize
|
|
2941
|
|
2942 @item modify
|
|
2943 A flag, @code{t} if the encoding function modifies the buffer, and
|
|
2944 @code{nil} if it works by returning a list of annotations.
|
|
2945
|
|
2946 @item mode-fn
|
|
2947 A minor-mode function to call after visiting a file converted from this
|
|
2948 format. The function is called with one argument, the integer 1;
|
|
2949 that tells a minor-mode function to enable the mode.
|
|
2950 @end table
|
|
2951
|
|
2952 The function @code{insert-file-contents} automatically recognizes file
|
|
2953 formats when it reads the specified file. It checks the text of the
|
|
2954 beginning of the file against the regular expressions of the format
|
|
2955 definitions, and if it finds a match, it calls the decoding function for
|
|
2956 that format. Then it checks all the known formats over again.
|
|
2957 It keeps checking them until none of them is applicable.
|
|
2958
|
|
2959 Visiting a file, with @code{find-file-noselect} or the commands that use
|
|
2960 it, performs conversion likewise (because it calls
|
|
2961 @code{insert-file-contents}); it also calls the mode function for each
|
|
2962 format that it decodes. It stores a list of the format names in the
|
|
2963 buffer-local variable @code{buffer-file-format}.
|
|
2964
|
|
2965 @defvar buffer-file-format
|
|
2966 This variable states the format of the visited file. More precisely,
|
|
2967 this is a list of the file format names that were decoded in the course
|
|
2968 of visiting the current buffer's file. It is always buffer-local in all
|
|
2969 buffers.
|
|
2970 @end defvar
|
|
2971
|
|
2972 When @code{write-region} writes data into a file, it first calls the
|
|
2973 encoding functions for the formats listed in @code{buffer-file-format},
|
|
2974 in the order of appearance in the list.
|
|
2975
|
|
2976 @deffn Command format-write-file file format &optional confirm
|
|
2977 This command writes the current buffer contents into the file
|
|
2978 @var{file} in format @var{format}, and makes that format the default
|
|
2979 for future saves of the buffer. The argument @var{format} is a list
|
|
2980 of format names. Except for the @var{format} argument, this command
|
|
2981 is similar to @code{write-file}. In particular, @var{confirm} has the
|
|
2982 same meaning and interactive treatment as the corresponding argument
|
|
2983 to @code{write-file}. @xref{Definition of write-file}.
|
|
2984 @end deffn
|
|
2985
|
|
2986 @deffn Command format-find-file file format
|
|
2987 This command finds the file @var{file}, converting it according to
|
|
2988 format @var{format}. It also makes @var{format} the default if the
|
|
2989 buffer is saved later.
|
|
2990
|
|
2991 The argument @var{format} is a list of format names. If @var{format} is
|
|
2992 @code{nil}, no conversion takes place. Interactively, typing just
|
|
2993 @key{RET} for @var{format} specifies @code{nil}.
|
|
2994 @end deffn
|
|
2995
|
|
2996 @deffn Command format-insert-file file format &optional beg end
|
|
2997 This command inserts the contents of file @var{file}, converting it
|
|
2998 according to format @var{format}. If @var{beg} and @var{end} are
|
|
2999 non-@code{nil}, they specify which part of the file to read, as in
|
|
3000 @code{insert-file-contents} (@pxref{Reading from Files}).
|
|
3001
|
|
3002 The return value is like what @code{insert-file-contents} returns: a
|
|
3003 list of the absolute file name and the length of the data inserted
|
|
3004 (after conversion).
|
|
3005
|
|
3006 The argument @var{format} is a list of format names. If @var{format} is
|
|
3007 @code{nil}, no conversion takes place. Interactively, typing just
|
|
3008 @key{RET} for @var{format} specifies @code{nil}.
|
|
3009 @end deffn
|
|
3010
|
|
3011 @defvar buffer-auto-save-file-format
|
|
3012 This variable specifies the format to use for auto-saving. Its value is
|
|
3013 a list of format names, just like the value of
|
|
3014 @code{buffer-file-format}; however, it is used instead of
|
|
3015 @code{buffer-file-format} for writing auto-save files. If the value
|
|
3016 is @code{t}, the default, auto-saving uses the same format as a
|
|
3017 regular save in the same buffer. This variable is always buffer-local
|
|
3018 in all buffers.
|
|
3019 @end defvar
|
|
3020
|
|
3021 @node Format Conversion Piecemeal
|
|
3022 @subsection Piecemeal Specification
|
|
3023
|
|
3024 In contrast to the round-trip specification described in the previous
|
|
3025 subsection (@pxref{Format Conversion Round-Trip}), you can use the variables
|
|
3026 @code{after-insert-file-functions} and @code{write-region-annotate-functions}
|
|
3027 to separately control the respective reading and writing conversions.
|
|
3028
|
|
3029 Conversion starts with one representation and produces another
|
|
3030 representation. When there is only one conversion to do, there is no
|
|
3031 conflict about what to start with. However, when there are multiple
|
|
3032 conversions involved, conflict may arise when two conversions need to
|
|
3033 start with the same data.
|
|
3034
|
|
3035 This situation is best understood in the context of converting text
|
|
3036 properties during @code{write-region}. For example, the character at
|
|
3037 position 42 in a buffer is @samp{X} with a text property @code{foo}. If
|
|
3038 the conversion for @code{foo} is done by inserting into the buffer, say,
|
|
3039 @samp{FOO:}, then that changes the character at position 42 from
|
|
3040 @samp{X} to @samp{F}. The next conversion will start with the wrong
|
|
3041 data straight away.
|
|
3042
|
|
3043 To avoid conflict, cooperative conversions do not modify the buffer,
|
|
3044 but instead specify @dfn{annotations}, a list of elements of the form
|
|
3045 @code{(@var{position} . @var{string})}, sorted in order of increasing
|
|
3046 @var{position}.
|
|
3047
|
|
3048 If there is more than one conversion, @code{write-region} merges their
|
|
3049 annotations destructively into one sorted list. Later, when the text
|
|
3050 from the buffer is actually written to the file, it intermixes the
|
|
3051 specified annotations at the corresponding positions. All this takes
|
|
3052 place without modifying the buffer.
|
|
3053
|
|
3054 @c ??? What about ``overriding'' conversions like those allowed
|
|
3055 @c ??? for `write-region-annotate-functions', below? --ttn
|
|
3056
|
|
3057 In contrast, when reading, the annotations intermixed with the text
|
|
3058 are handled immediately. @code{insert-file-contents} sets point to the
|
|
3059 beginning of some text to be converted, then calls the conversion
|
|
3060 functions with the length of that text. These functions should always
|
|
3061 return with point at the beginning of the inserted text. This approach
|
|
3062 makes sense for reading because annotations removed by the first
|
|
3063 converter can't be mistakenly processed by a later converter.
|
|
3064
|
|
3065 Each conversion function should scan for the annotations it
|
|
3066 recognizes, remove the annotation, modify the buffer text (to set a text
|
|
3067 property, for example), and return the updated length of the text, as it
|
|
3068 stands after those changes. The value returned by one function becomes
|
|
3069 the argument to the next function.
|
|
3070
|
|
3071 @defvar write-region-annotate-functions
|
|
3072 A list of functions for @code{write-region} to call. Each function in
|
|
3073 the list is called with two arguments: the start and end of the region
|
|
3074 to be written. These functions should not alter the contents of the
|
|
3075 buffer. Instead, they should return annotations.
|
|
3076
|
|
3077 @c ??? Following adapted from comment in `build_annotations' (fileio.c).
|
|
3078 @c ??? Perhaps this is intended for internal use only?
|
|
3079 @c ??? Someone who understands this, please reword it. --ttn
|
|
3080 As a special case, if a function returns with a different buffer
|
|
3081 current, Emacs takes it to mean the current buffer contains altered text
|
|
3082 to be output, and discards all previous annotations because they should
|
|
3083 have been dealt with by this function.
|
|
3084 @end defvar
|
|
3085
|
|
3086 @defvar after-insert-file-functions
|
|
3087 Each function in this list is called by @code{insert-file-contents}
|
|
3088 with one argument, the number of characters inserted, and with point
|
|
3089 at the beginning of the inserted text. Each function should leave
|
|
3090 point unchanged, and return the new character count describing the
|
|
3091 inserted text as modified by the function.
|
|
3092 @c ??? The docstring mentions a handler from `file-name-handler-alist'
|
|
3093 @c "intercepting" `insert-file-contents'. Hmmm. --ttn
|
|
3094 @end defvar
|
|
3095
|
|
3096 We invite users to write Lisp programs to store and retrieve text
|
|
3097 properties in files, using these hooks, and thus to experiment with
|
|
3098 various data formats and find good ones. Eventually we hope users
|
|
3099 will produce good, general extensions we can install in Emacs.
|
|
3100
|
|
3101 We suggest not trying to handle arbitrary Lisp objects as text property
|
|
3102 names or values---because a program that general is probably difficult
|
|
3103 to write, and slow. Instead, choose a set of possible data types that
|
|
3104 are reasonably flexible, and not too hard to encode.
|
|
3105
|
|
3106 @ignore
|
|
3107 arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c
|
|
3108 @end ignore
|