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