Mercurial > emacs
annotate lispref/files.texi @ 7402:494ca99e9517
(calendar-mouse-print-dates): Add missing level of list
for Islamic, Revolutionary and Mayan calendars.
Delete duplicate entry for ISO calendar.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Sun, 08 May 1994 06:10:52 +0000 |
parents | 5a93e6fb43a4 |
children | 7db892210924 |
rev | line source |
---|---|
6555 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. | |
4 @c See the file elisp.texi for copying conditions. | |
5 @setfilename ../info/files | |
6 @node Files, Backups and Auto-Saving, Documentation, Top | |
7 @comment node-name, next, previous, up | |
8 @chapter Files | |
9 | |
10 In Emacs, you can find, create, view, save, and otherwise work with | |
11 files and file directories. This chapter describes most of the | |
12 file-related functions of Emacs Lisp, but a few others are described in | |
13 @ref{Buffers}, and those related to backups and auto-saving are | |
14 described in @ref{Backups and Auto-Saving}. | |
15 | |
16 @menu | |
17 * Visiting Files:: Reading files into Emacs buffers for editing. | |
18 * Saving Buffers:: Writing changed buffers back into files. | |
19 * Reading from Files:: Reading files into buffers without visiting. | |
20 * Writing to Files:: Writing new files from parts of buffers. | |
21 * File Locks:: Locking and unlocking files, to prevent | |
22 simultaneous editing by two people. | |
23 * Information about Files:: Testing existence, accessibility, size of files. | |
24 * Changing File Attributes:: Renaming files, changing protection, etc. | |
25 * File Names:: Decomposing and expanding file names. | |
26 * Contents of Directories:: Getting a list of the files in a directory. | |
27 * Create/Delete Dirs:: Creating and Deleting Directories. | |
28 * Magic File Names:: Defining "magic" special handling | |
29 for certain file names. | |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
30 * Files and MS-DOS:: Distinguishing text and binary files on MS-DOS. |
6555 | 31 @end menu |
32 | |
33 @node Visiting Files | |
34 @section Visiting Files | |
35 @cindex finding files | |
36 @cindex visiting files | |
37 | |
38 Visiting a file means reading a file into a buffer. Once this is | |
39 done, we say that the buffer is @dfn{visiting} that file, and call the | |
40 file ``the visited file'' of the buffer. | |
41 | |
42 A file and a buffer are two different things. A file is information | |
43 recorded permanently in the computer (unless you delete it). A buffer, | |
44 on the other hand, is information inside of Emacs that will vanish at | |
45 the end of the editing session (or when you kill the buffer). Usually, | |
46 a buffer contains information that you have copied from a file; then we | |
47 say the buffer is visiting that file. The copy in the buffer is what | |
48 you modify with editing commands. Such changes to the buffer do not | |
49 change the file; therefore, to make the changes permanent, you must | |
50 @dfn{save} the buffer, which means copying the altered buffer contents | |
51 back into the file. | |
52 | |
53 In spite of the distinction between files and buffers, people often | |
54 refer to a file when they mean a buffer and vice-versa. Indeed, we say, | |
55 ``I am editing a file,'' rather than, ``I am editing a buffer which I | |
56 will soon save as a file of the same name.'' Humans do not usually need | |
57 to make the distinction explicit. When dealing with a computer program, | |
58 however, it is good to keep the distinction in mind. | |
59 | |
60 @menu | |
61 * Visiting Functions:: The usual interface functions for visiting. | |
62 * Subroutines of Visiting:: Lower-level subroutines that they use. | |
63 @end menu | |
64 | |
65 @node Visiting Functions | |
66 @subsection Functions for Visiting Files | |
67 | |
68 This section describes the functions normally used to visit files. | |
69 For historical reasons, these functions have names starting with | |
70 @samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for | |
71 functions and variables that access the visited file name of a buffer or | |
72 that find an existing buffer by its visited file name. | |
73 | |
74 @deffn Command find-file filename | |
75 This command selects a buffer visiting the file @var{filename}, | |
76 using an existing buffer if there is one, and otherwise creating a | |
77 new buffer and reading the file into it. It also returns that buffer. | |
78 | |
79 The body of the @code{find-file} function is very simple and looks | |
80 like this: | |
81 | |
82 @example | |
83 (switch-to-buffer (find-file-noselect filename)) | |
84 @end example | |
85 | |
86 @noindent | |
87 (See @code{switch-to-buffer} in @ref{Displaying Buffers}.) | |
88 | |
89 When @code{find-file} is called interactively, it prompts for | |
90 @var{filename} in the minibuffer. | |
91 @end deffn | |
92 | |
93 @defun find-file-noselect filename | |
94 This function is the guts of all the file-visiting functions. It finds | |
95 or creates a buffer visiting the file @var{filename}, and returns it. | |
96 It uses an existing buffer if there is one, and otherwise creates a new | |
97 buffer and reads the file into it. You may make the buffer current or | |
98 display it in a window if you wish, but this function does not do so. | |
99 | |
100 When @code{find-file-noselect} uses an existing buffer, it first | |
101 verifies that the file has not changed since it was last visited or | |
102 saved in that buffer. If the file has changed, then this function asks | |
103 the user whether to reread the changed file. If the user says | |
104 @samp{yes}, any changes previously made in the buffer are lost. | |
105 | |
106 If @code{find-file-noselect} needs to create a buffer, and there is no | |
107 file named @var{filename}, it displays the message @samp{New file} in | |
108 the echo area, and leaves the buffer empty. | |
109 | |
110 The @code{find-file-noselect} function calls @code{after-find-file} | |
111 after reading the file (@pxref{Subroutines of Visiting}). That function | |
112 sets the buffer major mode, parses local variables, warns the user if | |
113 there exists an auto-save file more recent than the file just visited, | |
114 and finishes by running the functions in @code{find-file-hooks}. | |
115 | |
116 The @code{find-file-noselect} function returns the buffer that is | |
117 visiting the file @var{filename}. | |
118 | |
119 @example | |
120 @group | |
121 (find-file-noselect "/etc/fstab") | |
122 @result{} #<buffer fstab> | |
123 @end group | |
124 @end example | |
125 @end defun | |
126 | |
127 @deffn Command find-alternate-file filename | |
128 This command selects a buffer visiting the file @var{filename}, then | |
129 kills the buffer that was previously displayed in the selected window. | |
130 It is useful if you have visited the wrong file by mistake, so that you | |
131 can get rid of the buffer that you did not want to create, at the same | |
132 time as you visit the file you intended. | |
133 | |
134 When this command is called interactively, it prompts for @var{filename}. | |
135 @end deffn | |
136 | |
137 @deffn Command find-file-other-window filename | |
138 This command selects a buffer visiting the file @var{filename}, but | |
139 does so in a window other than the selected window. It may use another | |
140 existing window or split a window; see @ref{Displaying Buffers}. | |
141 | |
142 When this command is called interactively, it prompts for | |
143 @var{filename}. | |
144 @end deffn | |
145 | |
146 @deffn Command find-file-read-only filename | |
147 This command selects a buffer visiting the file @var{filename}, like | |
148 @code{find-file}, but it marks the buffer as read-only. @xref{Read Only | |
149 Buffers}, for related functions and variables. | |
150 | |
151 When this command is called interactively, it prompts for | |
152 @var{filename}. | |
153 @end deffn | |
154 | |
155 @deffn Command view-file filename | |
156 This command views @var{filename} in View mode, returning to the | |
157 previous buffer when done. View mode is a mode that allows you to skim | |
158 rapidly through the file but does not let you modify it. Entering View | |
159 mode runs the normal hook @code{view-mode-hook}. @xref{Hooks}. | |
160 | |
161 When @code{view-file} is called interactively, it prompts for | |
162 @var{filename}. | |
163 @end deffn | |
164 | |
165 @defvar find-file-hooks | |
166 The value of this variable is a list of functions to be called after a | |
167 file is visited. The file's local-variables specification (if any) will | |
168 have been processed before the hooks are run. The buffer visiting the | |
169 file is current when the hook functions are run. | |
170 | |
171 This variable works just like a normal hook, but we think that renaming | |
172 it would not be advisable. | |
173 @end defvar | |
174 | |
175 @defvar find-file-not-found-hooks | |
176 The value of this variable is a list of functions to be called when | |
177 @code{find-file} or @code{find-file-noselect} is passed a nonexistent | |
178 file name. @code{find-file-noselect} calls these functions as soon as | |
179 it detects a nonexistent file. It calls them in the order of the list, | |
180 until one of them returns non-@code{nil}. @code{buffer-file-name} is | |
181 already set up. | |
182 | |
183 This is not a normal hook because the values of the functions are | |
184 used and they may not all be called. | |
185 @end defvar | |
186 | |
187 @node Subroutines of Visiting | |
188 @comment node-name, next, previous, up | |
189 @subsection Subroutines of Visiting | |
190 | |
191 The @code{find-file-noselect} function uses the | |
192 @code{create-file-buffer} and @code{after-find-file} functions as | |
193 subroutines. Sometimes it is useful to call them directly. | |
194 | |
195 @defun create-file-buffer filename | |
196 This function creates a suitably named buffer for visiting | |
197 @var{filename}, and returns it. It uses @var{filename} (sans directory) | |
198 as the name if that name is free; otherwise, it appends a string such as | |
199 @samp{<2>} to get an unused name. See also @ref{Creating Buffers}. | |
200 | |
201 @strong{Please note:} @code{create-file-buffer} does @emph{not} | |
202 associate the new buffer with a file and does not select the buffer. | |
203 | |
204 @example | |
205 @group | |
206 (create-file-buffer "foo") | |
207 @result{} #<buffer foo> | |
208 @end group | |
209 @group | |
210 (create-file-buffer "foo") | |
211 @result{} #<buffer foo<2>> | |
212 @end group | |
213 @group | |
214 (create-file-buffer "foo") | |
215 @result{} #<buffer foo<3>> | |
216 @end group | |
217 @end example | |
218 | |
219 This function is used by @code{find-file-noselect}. | |
220 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}). | |
221 @end defun | |
222 | |
223 @defun after-find-file &optional error warn | |
224 This function sets the buffer major mode, and parses local variables | |
225 (@pxref{Auto Major Mode}). It is called by @code{find-file-noselect} | |
226 and by the default revert function (@pxref{Reverting}). | |
227 | |
228 @cindex new file message | |
229 @cindex file open error | |
230 If reading the file got an error because the file does not exist, but | |
231 its directory does exist, the caller should pass a non-@code{nil} value | |
232 for @var{error}. In that case, @code{after-find-file} issues a warning: | |
233 @samp{(New File)}. For more serious errors, the caller should usually not | |
234 call @code{after-find-file}. | |
235 | |
236 If @var{warn} is non-@code{nil}, then this function issues a warning | |
237 if an auto-save file exists and is more recent than the visited file. | |
238 | |
239 The last thing @code{after-find-file} does is call all the functions | |
240 in @code{find-file-hooks}. | |
241 @end defun | |
242 | |
243 @node Saving Buffers | |
244 @section Saving Buffers | |
245 | |
246 When you edit a file in Emacs, you are actually working on a buffer | |
247 that is visiting that file---that is, the contents of the file are | |
248 copied into the buffer and the copy is what you edit. Changes to the | |
249 buffer do not change the file until you @dfn{save} the buffer, which | |
250 means copying the contents of the buffer into the file. | |
251 | |
252 @deffn Command save-buffer &optional backup-option | |
253 This function saves the contents of the current buffer in its visited | |
254 file if the buffer has been modified since it was last visited or saved. | |
255 Otherwise it does nothing. | |
256 | |
257 @code{save-buffer} is responsible for making backup files. Normally, | |
258 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup | |
259 file only if this is the first save or if the buffer was previously | |
260 modified. Other values for @var{backup-option} request the making of | |
261 backup files in other circumstances: | |
262 | |
263 @itemize @bullet | |
264 @item | |
265 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the | |
266 @code{save-buffer} function marks this version of the file to be | |
267 backed up when the buffer is next saved. | |
268 | |
269 @item | |
270 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the | |
271 @code{save-buffer} function unconditionally backs up the previous | |
272 version of the file before saving it. | |
273 @end itemize | |
274 @end deffn | |
275 | |
276 @deffn Command save-some-buffers &optional save-silently-p exiting | |
277 This command saves some modified file-visiting buffers. Normally it | |
278 asks the user about each buffer. But if @var{save-silently-p} is | |
279 non-@code{nil}, it saves all the file-visiting buffers without querying | |
280 the user. | |
281 | |
282 The optional @var{exiting} argument, if non-@code{nil}, requests this | |
283 function to offer also to save certain other buffers that are not | |
284 visiting files. These are buffers that have a non-@code{nil} local | |
285 value of @code{buffer-offer-save}. (A user who says yes to saving one | |
286 of these is asked to specify a file name to use.) The | |
287 @code{save-buffers-kill-emacs} function passes a non-@code{nil} value | |
288 for this argument. | |
289 @end deffn | |
290 | |
291 @defvar buffer-offer-save | |
292 When this variable is non-@code{nil} in a buffer, Emacs offers to save | |
293 the buffer on exit even if the buffer is not visiting a file. The | |
294 variable is automatically local in all buffers. Normally, Mail mode | |
295 (used for editing outgoing mail) sets this to @code{t}. | |
296 @end defvar | |
297 | |
298 @deffn Command write-file filename | |
299 This function writes the current buffer into file @var{filename}, makes | |
300 the buffer visit that file, and marks it not modified. Then it renames | |
301 the buffer based on @var{filename}, appending a string like @samp{<2>} | |
302 if necessary to make a unique buffer name. It does most of this work by | |
303 calling @code{set-visited-file-name} and @code{save-buffer}. | |
304 @end deffn | |
305 | |
306 @defvar write-file-hooks | |
307 The value of this variable is a list of functions to be called before | |
308 writing out a buffer to its visited file. If one of them returns | |
309 non-@code{nil}, the file is considered already written and the rest of | |
310 the functions are not called, nor is the usual code for writing the file | |
311 executed. | |
312 | |
313 If a function in @code{write-file-hooks} returns non-@code{nil}, it | |
314 is responsible for making a backup file (if that is appropriate). | |
315 To do so, execute the following code: | |
316 | |
317 @example | |
318 (or buffer-backed-up (backup-buffer)) | |
319 @end example | |
320 | |
321 You might wish to save the file modes value returned by | |
322 @code{backup-buffer} and use that to set the mode bits of the file that | |
323 you write. This is what @code{save-buffer} normally does. | |
324 | |
325 Even though this is not a normal hook, you can use @code{add-hook} and | |
326 @code{remove-hook} to manipulate the list. @xref{Hooks}. | |
327 @end defvar | |
328 | |
329 @c Emacs 19 feature | |
330 @defvar local-write-file-hooks | |
331 This works just like @code{write-file-hooks}, but it is intended | |
332 to be made local to particular buffers. It's not a good idea to make | |
333 @code{write-file-hooks} local to a buffer---use this variable instead. | |
334 | |
335 The variable is marked as a permanent local, so that changing the major | |
336 mode does not alter a buffer-local value. This is convenient for | |
337 packages that read ``file'' contents in special ways, and set up hooks | |
338 to save the data in a corresponding way. | |
339 @end defvar | |
340 | |
341 @c Emacs 19 feature | |
342 @defvar write-contents-hooks | |
343 This works just like @code{write-file-hooks}, but it is intended for | |
344 hooks that pertain to the contents of the file, as opposed to hooks that | |
345 pertain to where the file came from. Typically major mode commands make | |
346 buffer-local bindings for this variable. | |
347 @end defvar | |
348 | |
349 @c Emacs 19 feature | |
350 @defvar after-save-hook | |
351 This normal hook runs after a buffer has been saved in its visited file. | |
352 @end defvar | |
353 | |
354 @defvar file-precious-flag | |
355 If this variable is non-@code{nil}, then @code{save-buffer} protects | |
356 against I/O errors while saving by writing the new file to a temporary | |
357 name instead of the name it is supposed to have, and then renaming it to | |
358 the intended name after it is clear there are no errors. This procedure | |
359 prevents problems such as a lack of disk space from resulting in an | |
360 invalid file. | |
361 | |
362 (This feature worked differently in older Emacs versions.) | |
363 | |
364 Some modes set this non-@code{nil} locally in particular buffers. | |
365 @end defvar | |
366 | |
367 @defopt require-final-newline | |
368 This variable determines whether files may be written out that do | |
369 @emph{not} end with a newline. If the value of the variable is | |
370 @code{t}, then @code{save-buffer} silently adds a newline at the end of | |
371 the file whenever the buffer being saved does not already end in one. | |
372 If the value of the variable is non-@code{nil}, but not @code{t}, then | |
373 @code{save-buffer} asks the user whether to add a newline each time the | |
374 case arises. | |
375 | |
376 If the value of the variable is @code{nil}, then @code{save-buffer} | |
377 doesn't add newlines at all. @code{nil} is the default value, but a few | |
378 major modes set it to @code{t} in particular buffers. | |
379 @end defopt | |
380 | |
381 @node Reading from Files | |
382 @comment node-name, next, previous, up | |
383 @section Reading from Files | |
384 | |
385 You can copy a file from the disk and insert it into a buffer | |
386 using the @code{insert-file-contents} function. Don't use the user-level | |
387 command @code{insert-file} in a Lisp program, as that sets the mark. | |
388 | |
389 @defun insert-file-contents filename &optional visit beg end replace | |
390 This function inserts the contents of file @var{filename} into the | |
391 current buffer after point. It returns a list of the absolute file name | |
392 and the length of the data inserted. An error is signaled if | |
393 @var{filename} is not the name of a file that can be read. | |
394 | |
395 To set up saved text properties, @code{insert-file-contents} calls the | |
396 functions in the list @code{after-insert-file-functions}. For more | |
397 information, see @ref{Saving Properties}. | |
398 | |
399 If @var{visit} is non-@code{nil}, this function additionally marks the | |
400 buffer as unmodified and sets up various fields in the buffer so that it | |
401 is visiting the file @var{filename}: these include the buffer's visited | |
402 file name and its last save file modtime. This feature is used by | |
403 @code{find-file-noselect} and you probably should not use it yourself. | |
404 | |
405 If @var{beg} and @var{end} are non-@code{nil}, they should be integers | |
406 specifying the portion of the file to insert. In this case, @var{visit} | |
407 must be @code{nil}. For example, | |
408 | |
409 @example | |
410 (insert-file-contents filename nil 0 500) | |
411 @end example | |
412 | |
413 @noindent | |
414 inserts the first 500 characters of a file. | |
415 | |
416 If the argument @var{replace} is non-@code{nil}, it means to replace the | |
417 contents of the buffer (actually, just the accessible portion) with the | |
418 contents of the file. This is better than simply deleting the buffer | |
419 contents and inserting the whole file, because (1) it preserves some | |
420 marker positions and (2) it puts less data in the undo list. | |
421 @end defun | |
422 | |
423 If you want to pass a file name to another process so that another | |
424 program can read the file, use the function @code{file-local-copy}; see | |
425 @ref{Magic File Names}. | |
426 | |
427 @node Writing to Files | |
428 @comment node-name, next, previous, up | |
429 @section Writing to Files | |
430 | |
431 You can write the contents of a buffer, or part of a buffer, directly | |
432 to a file on disk using the @code{append-to-file} and | |
433 @code{write-region} functions. Don't use these functions to write to | |
434 files that are being visited; that could cause confusion in the | |
435 mechanisms for visiting. | |
436 | |
437 @deffn Command append-to-file start end filename | |
438 This function appends the contents of the region delimited by | |
439 @var{start} and @var{end} in the current buffer to the end of file | |
440 @var{filename}. If that file does not exist, it is created. This | |
441 function returns @code{nil}. | |
442 | |
443 An error is signaled if @var{filename} specifies a nonwritable file, | |
444 or a nonexistent file in a directory where files cannot be created. | |
445 @end deffn | |
446 | |
447 @deffn Command write-region start end filename &optional append visit | |
448 This function writes the region delimited by @var{start} and @var{end} | |
449 in the current buffer into the file specified by @var{filename}. | |
450 | |
451 @c Emacs 19 feature | |
452 If @var{start} is a string, then @code{write-region} writes or appends | |
453 that string, rather than text from the buffer. | |
454 | |
455 If @var{append} is non-@code{nil}, then the specified text is appended | |
456 to the existing file contents (if any). | |
457 | |
458 If @var{visit} is @code{t}, then Emacs establishes an association | |
459 between the buffer and the file: the buffer is then visiting that file. | |
460 It also sets the last file modification time for the current buffer to | |
461 @var{filename}'s modtime, and marks the buffer as not modified. This | |
462 feature is used by @code{save-buffer}, but you probably should not use | |
463 it yourself. | |
464 | |
465 @c Emacs 19 feature | |
466 If @var{visit} is a string, it specifies the file name to visit. This | |
467 way, you can write the data to one file (@var{filename}) while recording | |
468 the buffer as visiting another file (@var{visit}). The argument | |
469 @var{visit} is used in the echo area message and also for file locking; | |
470 @var{visit} is stored in @code{buffer-file-name}. This feature is used | |
471 to implement @code{file-precious-flag}; don't use it yourself unless you | |
472 really know what you're doing. | |
473 | |
474 To output information about text properties, @code{write-region} calls | |
475 the functions in the list @code{write-region-annotation-functions}. For | |
476 more information, see @ref{Saving Properties}. | |
477 | |
478 Normally, @code{write-region} displays a message @samp{Wrote file | |
479 @var{filename}} in the echo area. If @var{visit} is neither @code{t} | |
480 nor @code{nil} nor a string, then this message is inhibited. This | |
481 feature is useful for programs that use files for internal purposes, | |
482 files which the user does not need to know about. | |
483 @end deffn | |
484 | |
485 @node File Locks | |
486 @section File Locks | |
487 @cindex file locks | |
488 | |
489 When two users edit the same file at the same time, they are likely to | |
490 interfere with each other. Emacs tries to prevent this situation from | |
491 arising by recording a @dfn{file lock} when a file is being modified. | |
492 Emacs can then detect the first attempt to modify a buffer visiting a | |
493 file that is locked by another Emacs job, and ask the user what to do. | |
494 | |
495 File locks do not work properly when multiple machines can share | |
496 file systems, such as with NFS. Perhaps a better file locking system | |
497 will be implemented in the future. When file locks do not work, it is | |
498 possible for two users to make changes simultaneously, but Emacs can | |
499 still warn the user who saves second. Also, the detection of | |
500 modification of a buffer visiting a file changed on disk catches some | |
501 cases of simultaneous editing; see @ref{Modification Time}. | |
502 | |
503 @defun file-locked-p filename | |
504 This function returns @code{nil} if the file @var{filename} is not | |
505 locked by this Emacs process. It returns @code{t} if it is locked by | |
506 this Emacs, and it returns the name of the user who has locked it if it | |
507 is locked by someone else. | |
508 | |
509 @example | |
510 @group | |
511 (file-locked-p "foo") | |
512 @result{} nil | |
513 @end group | |
514 @end example | |
515 @end defun | |
516 | |
517 @defun lock-buffer &optional filename | |
518 This function locks the file @var{filename}, if the current buffer is | |
519 modified. The argument @var{filename} defaults to the current buffer's | |
520 visited file. Nothing is done if the current buffer is not visiting a | |
521 file, or is not modified. | |
522 @end defun | |
523 | |
524 @defun unlock-buffer | |
525 This function unlocks the file being visited in the current buffer, | |
526 if the buffer is modified. If the buffer is not modified, then | |
527 the file should not be locked, so this function does nothing. It also | |
528 does nothing if the current buffer is not visiting a file. | |
529 @end defun | |
530 | |
531 @defun ask-user-about-lock file other-user | |
532 This function is called when the user tries to modify @var{file}, but it | |
533 is locked by another user name @var{other-user}. The value it returns | |
534 determines what happens next: | |
535 | |
536 @itemize @bullet | |
537 @item | |
538 A value of @code{t} says to grab the lock on the file. Then | |
539 this user may edit the file and @var{other-user} loses the lock. | |
540 | |
541 @item | |
542 A value of @code{nil} says to ignore the lock and let this | |
543 user edit the file anyway. | |
544 | |
545 @item | |
546 @kindex file-locked | |
547 This function may instead signal a @code{file-locked} error, in which | |
548 case the change that the user was about to make does not take place. | |
549 | |
550 The error message for this error looks like this: | |
551 | |
552 @example | |
553 @error{} File is locked: @var{file} @var{other-user} | |
554 @end example | |
555 | |
556 @noindent | |
557 where @code{file} is the name of the file and @var{other-user} is the | |
558 name of the user who has locked the file. | |
559 @end itemize | |
560 | |
561 The default definition of this function asks the user to choose what | |
562 to do. If you wish, you can replace the @code{ask-user-about-lock} | |
563 function with your own version that decides in another way. The code | |
564 for its usual definition is in @file{userlock.el}. | |
565 @end defun | |
566 | |
567 @node Information about Files | |
568 @section Information about Files | |
569 | |
570 The functions described in this section are similar in as much as | |
571 they all operate on strings which are interpreted as file names. All | |
572 have names that begin with the word @samp{file}. These functions all | |
573 return information about actual files or directories, so their | |
574 arguments must all exist as actual files or directories unless | |
575 otherwise noted. | |
576 | |
577 Most of the file-oriented functions take a single argument, | |
578 @var{filename}, which must be a string. The file name is expanded using | |
579 @code{expand-file-name}, so @file{~} is handled correctly, as are | |
580 relative file names (including @samp{../}). These functions don't | |
581 recognize environment variable substitutions such as @samp{$HOME}. | |
582 @xref{File Name Expansion}. | |
583 | |
584 @menu | |
585 * Testing Accessibility:: Is a given file readable? Writable? | |
586 * Kinds of Files:: Is it a directory? A symbolic link? | |
587 * Truenames:: Eliminating symbolic links from a file name. | |
588 * File Attributes:: How large is it? Any other names? Etc. | |
589 @end menu | |
590 | |
591 @node Testing Accessibility | |
592 @comment node-name, next, previous, up | |
593 @subsection Testing Accessibility | |
594 @cindex accessibility of a file | |
595 @cindex file accessibility | |
596 | |
597 These functions test for permission to access a file in specific ways. | |
598 | |
599 @defun file-exists-p filename | |
600 This function returns @code{t} if a file named @var{filename} appears | |
601 to exist. This does not mean you can necessarily read the file, only | |
602 that you can find out its attributes. (On Unix, this is true if the | |
603 file exists and you have execute permission on the containing | |
604 directories, regardless of the protection of the file itself.) | |
605 | |
606 If the file does not exist, or if fascist access control policies | |
607 prevent you from finding the attributes of the file, this function | |
608 returns @code{nil}. | |
609 @end defun | |
610 | |
611 @defun file-readable-p filename | |
612 This function returns @code{t} if a file named @var{filename} exists | |
613 and you can read it. It returns @code{nil} otherwise. | |
614 | |
615 @example | |
616 @group | |
617 (file-readable-p "files.texi") | |
618 @result{} t | |
619 @end group | |
620 @group | |
621 (file-exists-p "/usr/spool/mqueue") | |
622 @result{} t | |
623 @end group | |
624 @group | |
625 (file-readable-p "/usr/spool/mqueue") | |
626 @result{} nil | |
627 @end group | |
628 @end example | |
629 @end defun | |
630 | |
631 @c Emacs 19 feature | |
632 @defun file-executable-p filename | |
633 This function returns @code{t} if a file named @var{filename} exists and | |
634 you can execute it. It returns @code{nil} otherwise. If the file is a | |
635 directory, execute permission means you can check the existence and | |
636 attributes of files inside the directory, and open those files if their | |
637 modes permit. | |
638 @end defun | |
639 | |
640 @defun file-writable-p filename | |
641 This function returns @code{t} if the file @var{filename} can be written or | |
642 created by you. It is writable if the file exists and you can write it. | |
643 It is creatable if the file does not exist, but the specified directory | |
644 does exist and you can write in that directory. @code{file-writable-p} | |
645 returns @code{nil} otherwise. | |
646 | |
647 In the third example below, @file{foo} is not writable because the | |
648 parent directory does not exist, even though the user could create such | |
649 a directory. | |
650 | |
651 @example | |
652 @group | |
653 (file-writable-p "~/foo") | |
654 @result{} t | |
655 @end group | |
656 @group | |
657 (file-writable-p "/foo") | |
658 @result{} nil | |
659 @end group | |
660 @group | |
661 (file-writable-p "~/no-such-dir/foo") | |
662 @result{} nil | |
663 @end group | |
664 @end example | |
665 @end defun | |
666 | |
667 @c Emacs 19 feature | |
668 @defun file-accessible-directory-p dirname | |
669 This function returns @code{t} if you have permission to open existing | |
670 files in directory @var{dirname}; otherwise (and if there is no such | |
671 directory), it returns @code{nil}. The value of @var{dirname} may be | |
672 either a directory name or the file name of a directory. | |
673 | |
674 Example: after the following, | |
675 | |
676 @example | |
677 (file-accessible-directory-p "/foo") | |
678 @result{} nil | |
679 @end example | |
680 | |
681 @noindent | |
682 we can deduce that any attempt to read a file in @file{/foo/} will | |
683 give an error. | |
684 @end defun | |
685 | |
686 @defun file-newer-than-file-p filename1 filename2 | |
687 @cindex file age | |
688 @cindex file modification time | |
689 This functions returns @code{t} if the file @var{filename1} is | |
690 newer than file @var{filename2}. If @var{filename1} does not | |
691 exist, it returns @code{nil}. If @var{filename2} does not exist, | |
692 it returns @code{t}. | |
693 | |
694 In the following example, assume that the file @file{aug-19} was | |
695 written on the 19th, and @file{aug-20} was written on the 20th. The | |
696 file @file{no-file} doesn't exist at all. | |
697 | |
698 @example | |
699 @group | |
700 (file-newer-than-file-p "aug-19" "aug-20") | |
701 @result{} nil | |
702 @end group | |
703 @group | |
704 (file-newer-than-file-p "aug-20" "aug-19") | |
705 @result{} t | |
706 @end group | |
707 @group | |
708 (file-newer-than-file-p "aug-19" "no-file") | |
709 @result{} t | |
710 @end group | |
711 @group | |
712 (file-newer-than-file-p "no-file" "aug-19") | |
713 @result{} nil | |
714 @end group | |
715 @end example | |
716 | |
717 You can use @code{file-attributes} to get a file's last modification | |
718 time as a list of two numbers. @xref{File Attributes}. | |
719 @end defun | |
720 | |
721 @node Kinds of Files | |
722 @comment node-name, next, previous, up | |
723 @subsection Distinguishing Kinds of Files | |
724 | |
725 This section describes how to distinguish directories and symbolic | |
726 links from ordinary files. | |
727 | |
728 @defun file-symlink-p filename | |
729 @cindex file symbolic links | |
730 If the file @var{filename} is a symbolic link, the @code{file-symlink-p} | |
731 function returns the file name to which it is linked. This may be the | |
732 name of a text file, a directory, or even another symbolic link, or of | |
733 no file at all. | |
734 | |
735 If the file @var{filename} is not a symbolic link (or there is no such file), | |
736 @code{file-symlink-p} returns @code{nil}. | |
737 | |
738 @example | |
739 @group | |
740 (file-symlink-p "foo") | |
741 @result{} nil | |
742 @end group | |
743 @group | |
744 (file-symlink-p "sym-link") | |
745 @result{} "foo" | |
746 @end group | |
747 @group | |
748 (file-symlink-p "sym-link2") | |
749 @result{} "sym-link" | |
750 @end group | |
751 @group | |
752 (file-symlink-p "/bin") | |
753 @result{} "/pub/bin" | |
754 @end group | |
755 @end example | |
756 | |
757 @c !!! file-symlink-p: should show output of ls -l for comparison | |
758 @end defun | |
759 | |
760 @defun file-directory-p filename | |
761 This function returns @code{t} if @var{filename} is the name of an | |
762 existing directory, @code{nil} otherwise. | |
763 | |
764 @example | |
765 @group | |
766 (file-directory-p "~rms") | |
767 @result{} t | |
768 @end group | |
769 @group | |
770 (file-directory-p "~rms/lewis/files.texi") | |
771 @result{} nil | |
772 @end group | |
773 @group | |
774 (file-directory-p "~rms/lewis/no-such-file") | |
775 @result{} nil | |
776 @end group | |
777 @group | |
778 (file-directory-p "$HOME") | |
779 @result{} nil | |
780 @end group | |
781 @group | |
782 (file-directory-p | |
783 (substitute-in-file-name "$HOME")) | |
784 @result{} t | |
785 @end group | |
786 @end example | |
787 @end defun | |
788 | |
789 @node Truenames | |
790 @subsection Truenames | |
791 @cindex truename (of file) | |
792 | |
793 @c Emacs 19 features | |
794 The @dfn{truename} of a file is the name that you get by following | |
795 symbolic links until none remain, then expanding to get rid of @samp{.} | |
796 and @samp{..} as components. Strictly speaking, a file need not have a | |
797 unique truename; the number of distinct truenames a file has is equal to | |
798 the number of hard links to the file. However, truenames are useful | |
799 because they eliminate symbolic links as a cause of name variation. | |
800 | |
801 @defun file-truename filename | |
802 The function @code{file-truename} returns the true name of the file | |
803 @var{filename}. This is the name that you get by following symbolic | |
804 links until none remain. The argument must be an absolute file name. | |
805 @end defun | |
806 | |
807 @xref{Buffer File Name}, for related information. | |
808 | |
809 @node File Attributes | |
810 @comment node-name, next, previous, up | |
811 @subsection Other Information about Files | |
812 | |
813 This section describes the functions for getting detailed information | |
814 about a file, other than its contents. This information includes the | |
815 mode bits that control access permission, the owner and group numbers, | |
816 the number of names, the inode number, the size, and the times of access | |
817 and modification. | |
818 | |
819 @defun file-modes filename | |
820 @cindex permission | |
821 @cindex file attributes | |
822 This function returns the mode bits of @var{filename}, as an integer. | |
823 The mode bits are also called the file permissions, and they specify | |
824 access control in the usual Unix fashion. If the low-order bit is 1, | |
825 then the file is executable by all users, if the second lowest-order bit | |
826 is 1, then the file is writable by all users, etc. | |
827 | |
828 The highest value returnable is 4095 (7777 octal), meaning that | |
829 everyone has read, write, and execute permission, that the @sc{suid} bit | |
830 is set for both others and group, and that the sticky bit is set. | |
831 | |
832 @example | |
833 @group | |
834 (file-modes "~/junk/diffs") | |
835 @result{} 492 ; @r{Decimal integer.} | |
836 @end group | |
837 @group | |
838 (format "%o" 492) | |
839 @result{} "754" ; @r{Convert to octal.} | |
840 @end group | |
841 | |
842 @group | |
843 (set-file-modes "~/junk/diffs" 438) | |
844 @result{} nil | |
845 @end group | |
846 | |
847 @group | |
848 (format "%o" 438) | |
849 @result{} "666" ; @r{Convert to octal.} | |
850 @end group | |
851 | |
852 @group | |
853 % ls -l diffs | |
854 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs | |
855 @end group | |
856 @end example | |
857 @end defun | |
858 | |
859 @defun file-nlinks filename | |
860 This functions returns the number of names (i.e., hard links) that | |
861 file @var{filename} has. If the file does not exist, then this function | |
862 returns @code{nil}. Note that symbolic links have no effect on this | |
863 function, because they are not considered to be names of the files they | |
864 link to. | |
865 | |
866 @example | |
867 @group | |
868 % ls -l foo* | |
869 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo | |
870 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1 | |
871 @end group | |
872 | |
873 @group | |
874 (file-nlinks "foo") | |
875 @result{} 2 | |
876 @end group | |
877 @group | |
878 (file-nlinks "doesnt-exist") | |
879 @result{} nil | |
880 @end group | |
881 @end example | |
882 @end defun | |
883 | |
884 @defun file-attributes filename | |
885 This function returns a list of attributes of file @var{filename}. If | |
886 the specified file cannot be opened, it returns @code{nil}. | |
887 | |
888 The elements of the list, in order, are: | |
889 | |
890 @enumerate 0 | |
891 @item | |
892 @code{t} for a directory, a string for a symbolic link (the name | |
893 linked to), or @code{nil} for a text file. | |
894 | |
895 @c Wordy so as to prevent an overfull hbox. --rjc 15mar92 | |
896 @item | |
897 The number of names the file has. Alternate names, also known as hard | |
898 links, can be created by using the @code{add-name-to-file} function | |
899 (@pxref{Changing File Attributes}). | |
900 | |
901 @item | |
902 The file's @sc{uid}. | |
903 | |
904 @item | |
905 The file's @sc{gid}. | |
906 | |
907 @item | |
908 The time of last access, as a list of two integers. | |
909 The first integer has the high-order 16 bits of time, | |
910 the second has the low 16 bits. (This is similar to the | |
911 value of @code{current-time}; see @ref{Time of Day}.) | |
912 | |
913 @item | |
914 The time of last modification as a list of two integers (as above). | |
915 | |
916 @item | |
917 The time of last status change as a list of two integers (as above). | |
918 | |
919 @item | |
920 The size of the file in bytes. | |
921 | |
922 @item | |
923 The file's modes, as a string of ten letters or dashes | |
924 as in @samp{ls -l}. | |
925 | |
926 @item | |
927 @code{t} if the file's @sc{gid} would change if file were | |
928 deleted and recreated; @code{nil} otherwise. | |
929 | |
930 @item | |
931 The file's inode number. | |
932 | |
933 @item | |
934 The file system number of the file system that the file is in. This | |
935 element together with the file's inode number, give enough information | |
936 to distinguish any two files on the system---no two files can have the | |
937 same values for both of these numbers. | |
938 @end enumerate | |
939 | |
940 For example, here are the file attributes for @file{files.texi}: | |
941 | |
942 @example | |
943 @group | |
944 (file-attributes "files.texi") | |
945 @result{} (nil | |
946 1 | |
947 2235 | |
948 75 | |
949 (8489 20284) | |
950 (8489 20284) | |
951 (8489 20285) | |
952 14906 | |
953 "-rw-rw-rw-" | |
954 nil | |
955 129500 | |
956 -32252) | |
957 @end group | |
958 @end example | |
959 | |
960 @noindent | |
961 and here is how the result is interpreted: | |
962 | |
963 @table @code | |
964 @item nil | |
965 is neither a directory nor a symbolic link. | |
966 | |
967 @item 1 | |
968 has only one name (the name @file{files.texi} in the current default | |
969 directory). | |
970 | |
971 @item 2235 | |
972 is owned by the user with @sc{uid} 2235. | |
973 | |
974 @item 75 | |
975 is in the group with @sc{gid} 75. | |
976 | |
977 @item (8489 20284) | |
978 was last accessed on Aug 19 00:09. Unfortunately, you cannot convert | |
979 this number into a time string in Emacs. | |
980 | |
981 @item (8489 20284) | |
982 was last modified on Aug 19 00:09. | |
983 | |
984 @item (8489 20285) | |
985 last had its inode changed on Aug 19 00:09. | |
986 | |
987 @item 14906 | |
988 is 14906 characters long. | |
989 | |
990 @item "-rw-rw-rw-" | |
991 has a mode of read and write access for the owner, group, and world. | |
992 | |
993 @item nil | |
994 would retain the same @sc{gid} if it were recreated. | |
995 | |
996 @item 129500 | |
997 has an inode number of 129500. | |
998 @item -32252 | |
999 is on file system number -32252. | |
1000 @end table | |
1001 @end defun | |
1002 | |
1003 @node Changing File Attributes | |
1004 @section Changing File Names and Attributes | |
1005 @cindex renaming files | |
1006 @cindex copying files | |
1007 @cindex deleting files | |
1008 @cindex linking files | |
1009 @cindex setting modes of files | |
1010 | |
1011 The functions in this section rename, copy, delete, link, and set the | |
1012 modes of files. | |
1013 | |
1014 In the functions that have an argument @var{newname}, if a file by the | |
1015 name of @var{newname} already exists, the actions taken depend on the | |
1016 value of the argument @var{ok-if-already-exists}: | |
1017 | |
1018 @itemize @bullet | |
1019 @item | |
1020 Signal a @code{file-already-exists} error if | |
1021 @var{ok-if-already-exists} is @code{nil}. | |
1022 | |
1023 @item | |
1024 Request confirmation if @var{ok-if-already-exists} is a number. | |
1025 | |
1026 @item | |
1027 Replace the old file without confirmation if @var{ok-if-already-exists} | |
1028 is any other value. | |
1029 @end itemize | |
1030 | |
1031 @defun add-name-to-file oldname newname &optional ok-if-already-exists | |
1032 @cindex file with multiple names | |
1033 @cindex file hard link | |
1034 This function gives the file named @var{oldname} the additional name | |
1035 @var{newname}. This means that @var{newname} becomes a new ``hard | |
1036 link'' to @var{oldname}. | |
1037 | |
1038 In the first part of the following example, we list two files, | |
1039 @file{foo} and @file{foo3}. | |
1040 | |
1041 @example | |
1042 @group | |
1043 % ls -l fo* | |
1044 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo | |
1045 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 | |
1046 @end group | |
1047 @end example | |
1048 | |
1049 Then we evaluate the form @code{(add-name-to-file "~/lewis/foo" | |
1050 "~/lewis/foo2")}. Again we list the files. This shows two names, | |
1051 @file{foo} and @file{foo2}. | |
1052 | |
1053 @example | |
1054 @group | |
1055 (add-name-to-file "~/lewis/foo1" "~/lewis/foo2") | |
1056 @result{} nil | |
1057 @end group | |
1058 | |
1059 @group | |
1060 % ls -l fo* | |
1061 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo | |
1062 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2 | |
1063 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 | |
1064 @end group | |
1065 @end example | |
1066 | |
1067 @c !!! Check whether this set of examples is consistent. --rjc 15mar92 | |
1068 Finally, we evaluate the following: | |
1069 | |
1070 @example | |
1071 (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t) | |
1072 @end example | |
1073 | |
1074 @noindent | |
1075 and list the files again. Now there are three names | |
1076 for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old | |
1077 contents of @file{foo3} are lost. | |
1078 | |
1079 @example | |
1080 @group | |
1081 (add-name-to-file "~/lewis/foo1" "~/lewis/foo3") | |
1082 @result{} nil | |
1083 @end group | |
1084 | |
1085 @group | |
1086 % ls -l fo* | |
1087 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo | |
1088 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2 | |
1089 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3 | |
1090 @end group | |
1091 @end example | |
1092 | |
1093 This function is meaningless on VMS, where multiple names for one file | |
1094 are not allowed. | |
1095 | |
1096 See also @code{file-nlinks} in @ref{File Attributes}. | |
1097 @end defun | |
1098 | |
1099 @deffn Command rename-file filename newname &optional ok-if-already-exists | |
1100 This command renames the file @var{filename} as @var{newname}. | |
1101 | |
1102 If @var{filename} has additional names aside from @var{filename}, it | |
1103 continues to have those names. In fact, adding the name @var{newname} | |
1104 with @code{add-name-to-file} and then deleting @var{filename} has the | |
1105 same effect as renaming, aside from momentary intermediate states. | |
1106 | |
1107 In an interactive call, this function prompts for @var{filename} and | |
1108 @var{newname} in the minibuffer; also, it requests confirmation if | |
1109 @var{newname} already exists. | |
1110 @end deffn | |
1111 | |
1112 @deffn Command copy-file oldname newname &optional ok-if-exists time | |
1113 This command copies the file @var{oldname} to @var{newname}. An | |
1114 error is signaled if @var{oldname} does not exist. | |
1115 | |
1116 If @var{time} is non-@code{nil}, then this functions gives the new | |
1117 file the same last-modified time that the old one has. (This works on | |
1118 only some operating systems.) | |
1119 | |
1120 In an interactive call, this function prompts for @var{filename} and | |
1121 @var{newname} in the minibuffer; also, it requests confirmation if | |
1122 @var{newname} already exists. | |
1123 @end deffn | |
1124 | |
1125 @deffn Command delete-file filename | |
1126 @pindex rm | |
1127 This command deletes the file @var{filename}, like the shell command | |
1128 @samp{rm @var{filename}}. If the file has multiple names, it continues | |
1129 to exist under the other names. | |
1130 | |
1131 A suitable kind of @code{file-error} error is signaled if the file | |
1132 does not exist, or is not deletable. (On Unix, a file is deletable if | |
1133 its directory is writable.) | |
1134 | |
1135 See also @code{delete-directory} in @ref{Create/Delete Dirs}. | |
1136 @end deffn | |
1137 | |
1138 @deffn Command make-symbolic-link filename newname &optional ok-if-exists | |
1139 @pindex ln | |
1140 @kindex file-already-exists | |
1141 This command makes a symbolic link to @var{filename}, named | |
1142 @var{newname}. This is like the shell command @samp{ln -s | |
1143 @var{filename} @var{newname}}. | |
1144 | |
1145 In an interactive call, @var{filename} and @var{newname} are read in the | |
1146 minibuffer; it requests confirmation if the file @var{newname} already | |
1147 exists. | |
1148 @end deffn | |
1149 | |
1150 @defun define-logical-name varname string | |
1151 This function defines the logical name @var{name} to have the value | |
1152 @var{string}. It is available only on VMS. | |
1153 @end defun | |
1154 | |
1155 @defun set-file-modes filename mode | |
1156 This function sets mode bits of @var{filename} to @var{mode} (which must | |
1157 be an integer). Only the 12 low bits of @var{mode} are used. | |
1158 @end defun | |
1159 | |
1160 @c Emacs 19 feature | |
1161 @defun set-default-file-modes mode | |
1162 This function sets the default file protection for new files created by | |
1163 Emacs and its subprocesses. Every file created with Emacs initially has | |
1164 this protection. On Unix, the default protection is the bitwise | |
1165 complement of the ``umask'' value. | |
1166 | |
1167 The argument @var{mode} must be an integer. Only the 9 low bits of | |
1168 @var{mode} are used. | |
1169 | |
1170 Saving a modified version of an existing file does not count as creating | |
1171 the file; it does not change the file's mode, and does not use the | |
1172 default file protection. | |
1173 @end defun | |
1174 | |
1175 @defun default-file-modes | |
1176 This function returns the current default protection value. | |
1177 @end defun | |
1178 | |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1179 @cindex MS-DOS and file modes |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1180 @cindex file modes and MS-DOS |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1181 On MS-DOS, there is no such thing as an ``executable'' file mode bit. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1182 So Emacs considers a file executable if its name ends in @samp{.com}, |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1183 @samp{.bat} or @samp{.exe}. This is reflected in the values returned |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1184 by @code{file-modes} and @code{file-attributes}. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1185 |
6555 | 1186 @node File Names |
1187 @section File Names | |
1188 @cindex file names | |
1189 | |
1190 Files are generally referred to by their names, in Emacs as elsewhere. | |
1191 File names in Emacs are represented as strings. The functions that | |
1192 operate on a file all expect a file name argument. | |
1193 | |
1194 In addition to operating on files themselves, Emacs Lisp programs | |
1195 often need to operate on the names; i.e., to take them apart and to use | |
1196 part of a name to construct related file names. This section describes | |
1197 how to manipulate file names. | |
1198 | |
1199 The functions in this section do not actually access files, so they | |
1200 can operate on file names that do not refer to an existing file or | |
1201 directory. | |
1202 | |
1203 On VMS, all these functions understand both VMS file name syntax and | |
1204 Unix syntax. This is so that all the standard Lisp libraries can | |
1205 specify file names in Unix syntax and work properly on VMS without | |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1206 change. On MS-DOS, these functions understand MS-DOS file name syntax |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1207 as well as Unix syntax. |
6555 | 1208 |
1209 @menu | |
1210 * File Name Components:: The directory part of a file name, and the rest. | |
1211 * Directory Names:: A directory's name as a directory | |
1212 is different from its name as a file. | |
1213 * Relative File Names:: Some file names are relative to a current directory. | |
1214 * File Name Expansion:: Converting relative file names to absolute ones. | |
1215 * Unique File Names:: Generating names for temporary files. | |
1216 * File Name Completion:: Finding the completions for a given file name. | |
1217 @end menu | |
1218 | |
1219 @node File Name Components | |
1220 @subsection File Name Components | |
1221 @cindex directory part (of file name) | |
1222 @cindex nondirectory part (of file name) | |
1223 @cindex version number (in file name) | |
1224 | |
1225 The operating system groups files into directories. To specify a | |
1226 file, you must specify the directory, and the file's name in that | |
1227 directory. Therefore, a file name in Emacs is considered to have two | |
1228 main parts: the @dfn{directory name} part, and the @dfn{nondirectory} | |
1229 part (or @dfn{file name within the directory}). Either part may be | |
1230 empty. Concatenating these two parts reproduces the original file name. | |
1231 | |
1232 On Unix, the directory part is everything up to and including the last | |
1233 slash; the nondirectory part is the rest. The rules in VMS syntax are | |
1234 complicated. | |
1235 | |
1236 For some purposes, the nondirectory part is further subdivided into | |
1237 the name proper and the @dfn{version number}. On Unix, only backup | |
1238 files have version numbers in their names; on VMS, every file has a | |
1239 version number, but most of the time the file name actually used in | |
1240 Emacs omits the version number. Version numbers are found mostly in | |
1241 directory lists. | |
1242 | |
1243 @defun file-name-directory filename | |
1244 This function returns the directory part of @var{filename} (or | |
1245 @code{nil} if @var{filename} does not include a directory part). On | |
1246 Unix, the function returns a string ending in a slash. On VMS, it | |
1247 returns a string ending in one of the three characters @samp{:}, | |
1248 @samp{]}, or @samp{>}. | |
1249 | |
1250 @example | |
1251 @group | |
1252 (file-name-directory "lewis/foo") ; @r{Unix example} | |
1253 @result{} "lewis/" | |
1254 @end group | |
1255 @group | |
1256 (file-name-directory "foo") ; @r{Unix example} | |
1257 @result{} nil | |
1258 @end group | |
1259 @group | |
1260 (file-name-directory "[X]FOO.TMP") ; @r{VMS example} | |
1261 @result{} "[X]" | |
1262 @end group | |
1263 @end example | |
1264 @end defun | |
1265 | |
1266 @defun file-name-nondirectory filename | |
1267 This function returns the nondirectory part of @var{filename}. | |
1268 | |
1269 @example | |
1270 @group | |
1271 (file-name-nondirectory "lewis/foo") | |
1272 @result{} "foo" | |
1273 @end group | |
1274 @group | |
1275 (file-name-nondirectory "foo") | |
1276 @result{} "foo" | |
1277 @end group | |
1278 @group | |
1279 ;; @r{The following example is accurate only on VMS.} | |
1280 (file-name-nondirectory "[X]FOO.TMP") | |
1281 @result{} "FOO.TMP" | |
1282 @end group | |
1283 @end example | |
1284 @end defun | |
1285 | |
1286 @defun file-name-sans-versions filename | |
1287 This function returns @var{filename} without any file version numbers, | |
1288 backup version numbers, or trailing tildes. | |
1289 | |
1290 @example | |
1291 @group | |
1292 (file-name-sans-versions "~rms/foo.~1~") | |
1293 @result{} "~rms/foo" | |
1294 @end group | |
1295 @group | |
1296 (file-name-sans-versions "~rms/foo~") | |
1297 @result{} "~rms/foo" | |
1298 @end group | |
1299 @group | |
1300 (file-name-sans-versions "~rms/foo") | |
1301 @result{} "~rms/foo" | |
1302 @end group | |
1303 @group | |
1304 ;; @r{The following example applies to VMS only.} | |
1305 (file-name-sans-versions "foo;23") | |
1306 @result{} "foo" | |
1307 @end group | |
1308 @end example | |
1309 @end defun | |
1310 | |
1311 @node Directory Names | |
1312 @comment node-name, next, previous, up | |
1313 @subsection Directory Names | |
1314 @cindex directory name | |
1315 @cindex file name of directory | |
1316 | |
1317 A @dfn{directory name} is the name of a directory. A directory is a | |
1318 kind of file, and it has a file name, which is related to the directory | |
1319 name but not identical to it. (This is not quite the same as the usual | |
1320 Unix terminology.) These two different names for the same entity are | |
1321 related by a syntactic transformation. On Unix, this is simple: a | |
1322 directory name ends in a slash, whereas the directory's name as a file | |
1323 lacks that slash. On VMS, the relationship is more complicated. | |
1324 | |
1325 The difference between a directory name and its name as a file is | |
1326 subtle but crucial. When an Emacs variable or function argument is | |
1327 described as being a directory name, a file name of a directory is not | |
1328 acceptable. | |
1329 | |
1330 These two functions convert between directory names and file names. | |
1331 They do nothing special with environment variable substitutions such as | |
1332 @samp{$HOME}, and the constructs @samp{~}, and @samp{..}. | |
1333 | |
1334 @defun file-name-as-directory filename | |
1335 This function returns a string representing @var{filename} in a form | |
1336 that the operating system will interpret as the name of a directory. In | |
1337 Unix, this means appending a slash to the string. On VMS, the function | |
1338 converts a string of the form @file{[X]Y.DIR.1} to the form | |
1339 @file{[X.Y]}. | |
1340 | |
1341 @example | |
1342 @group | |
1343 (file-name-as-directory "~rms/lewis") | |
1344 @result{} "~rms/lewis/" | |
1345 @end group | |
1346 @end example | |
1347 @end defun | |
1348 | |
1349 @defun directory-file-name dirname | |
1350 This function returns a string representing @var{dirname} in a form | |
1351 that the operating system will interpret as the name of a file. On | |
1352 Unix, this means removing a final slash from the string. On VMS, the | |
1353 function converts a string of the form @file{[X.Y]} to | |
1354 @file{[X]Y.DIR.1}. | |
1355 | |
1356 @example | |
1357 @group | |
1358 (directory-file-name "~lewis/") | |
1359 @result{} "~lewis" | |
1360 @end group | |
1361 @end example | |
1362 @end defun | |
1363 | |
1364 @cindex directory name abbreviation | |
1365 Directory name abbreviations are useful for directories that are | |
1366 normally accessed through symbolic links. Sometimes the users recognize | |
1367 primarily the link's name as ``the name'' of the directory, and find it | |
1368 annoying to see the directory's ``real'' name. If you define the link | |
1369 name as an abbreviation for the ``real'' name, Emacs shows users the | |
1370 abbreviation instead. | |
1371 | |
1372 @defvar directory-abbrev-alist | |
1373 The variable @code{directory-abbrev-alist} contains an alist of | |
1374 abbreviations to use for file directories. Each element has the form | |
1375 @code{(@var{from} . @var{to})}, and says to replace @var{from} with | |
1376 @var{to} when it appears in a directory name. The @var{from} string is | |
1377 actually a regular expression; it should always start with @samp{^}. | |
1378 The function @code{abbreviate-file-name} performs these substitutions. | |
1379 | |
1380 You can set this variable in @file{site-init.el} to describe the | |
1381 abbreviations appropriate for your site. | |
1382 | |
1383 Here's an example, from a system on which file system @file{/home/fsf} | |
1384 and so on are normally accessed through symbolic links named @file{/fsf} | |
1385 and so on. | |
1386 | |
1387 @example | |
1388 (("^/home/fsf" . "/fsf") | |
1389 ("^/home/gp" . "/gp") | |
1390 ("^/home/gd" . "/gd")) | |
1391 @end example | |
1392 @end defvar | |
1393 | |
1394 To convert a directory name to its abbreviation, use this | |
1395 function: | |
1396 | |
1397 @defun abbreviate-file-name dirname | |
1398 This function applies abbreviations from @code{directory-abbrev-alist} | |
1399 to its argument, and substitutes @samp{~} for the user's home | |
1400 directory. | |
1401 @end defun | |
1402 | |
1403 @node Relative File Names | |
1404 @subsection Absolute and Relative File Names | |
1405 @cindex absolute file name | |
1406 @cindex relative file name | |
1407 | |
1408 All the directories in the file system form a tree starting at the | |
1409 root directory. A file name can specify all the directory names | |
1410 starting from the root of the tree; then it is called an @dfn{absolute} | |
1411 file name. Or it can specify the position of the file in the tree | |
1412 relative to a default directory; then it is called a @dfn{relative} | |
1413 file name. On Unix, an absolute file name starts with a slash or a | |
1414 tilde (@samp{~}), and a relative one does not. The rules on VMS are | |
1415 complicated. | |
1416 | |
1417 @defun file-name-absolute-p filename | |
1418 This function returns @code{t} if file @var{filename} is an absolute | |
1419 file name, @code{nil} otherwise. On VMS, this function understands both | |
1420 Unix syntax and VMS syntax. | |
1421 | |
1422 @example | |
1423 @group | |
1424 (file-name-absolute-p "~rms/foo") | |
1425 @result{} t | |
1426 @end group | |
1427 @group | |
1428 (file-name-absolute-p "rms/foo") | |
1429 @result{} nil | |
1430 @end group | |
1431 @group | |
1432 (file-name-absolute-p "/user/rms/foo") | |
1433 @result{} t | |
1434 @end group | |
1435 @end example | |
1436 @end defun | |
1437 | |
1438 @node File Name Expansion | |
1439 @subsection Functions that Expand Filenames | |
1440 @cindex expansion of file names | |
1441 | |
1442 @dfn{Expansion} of a file name means converting a relative file name | |
1443 to an absolute one. Since this is done relative to a default directory, | |
1444 you must specify the default directory name as well as the file name to | |
1445 be expanded. Expansion also simplifies file names by eliminating | |
1446 redundancies such as @file{./} and @file{@var{name}/../}. | |
1447 | |
1448 @defun expand-file-name filename &optional directory | |
1449 This function converts @var{filename} to an absolute file name. If | |
1450 @var{directory} is supplied, it is the directory to start with if | |
1451 @var{filename} is relative. (The value of @var{directory} should itself | |
1452 be an absolute directory name; it may start with @samp{~}.) | |
1453 Otherwise, the current buffer's value of @code{default-directory} is | |
1454 used. For example: | |
1455 | |
1456 @example | |
1457 @group | |
1458 (expand-file-name "foo") | |
1459 @result{} "/xcssun/users/rms/lewis/foo" | |
1460 @end group | |
1461 @group | |
1462 (expand-file-name "../foo") | |
1463 @result{} "/xcssun/users/rms/foo" | |
1464 @end group | |
1465 @group | |
1466 (expand-file-name "foo" "/usr/spool/") | |
1467 @result{} "/usr/spool/foo" | |
1468 @end group | |
1469 @group | |
1470 (expand-file-name "$HOME/foo") | |
1471 @result{} "/xcssun/users/rms/lewis/$HOME/foo" | |
1472 @end group | |
1473 @end example | |
1474 | |
1475 Filenames containing @samp{.} or @samp{..} are simplified to their | |
1476 canonical form: | |
1477 | |
1478 @example | |
1479 @group | |
1480 (expand-file-name "bar/../foo") | |
1481 @result{} "/xcssun/users/rms/lewis/foo" | |
1482 @end group | |
1483 @end example | |
1484 | |
1485 @samp{~/} is expanded into the user's home directory. A @samp{/} or | |
1486 @samp{~} following a @samp{/} is taken to be the start of an absolute | |
1487 file name that overrides what precedes it, so everything before that | |
1488 @samp{/} or @samp{~} is deleted. For example: | |
1489 | |
1490 @example | |
1491 @group | |
1492 (expand-file-name | |
1493 "/a1/gnu//usr/local/lib/emacs/etc/MACHINES") | |
1494 @result{} "/usr/local/lib/emacs/etc/MACHINES" | |
1495 @end group | |
1496 @group | |
1497 (expand-file-name "/a1/gnu/~/foo") | |
1498 @result{} "/xcssun/users/rms/foo" | |
1499 @end group | |
1500 @end example | |
1501 | |
1502 @noindent | |
1503 In both cases, @file{/a1/gnu/} is discarded because an absolute file | |
1504 name follows it. | |
1505 | |
1506 Note that @code{expand-file-name} does @emph{not} expand environment | |
1507 variables; only @code{substitute-in-file-name} does that. | |
1508 @end defun | |
1509 | |
1510 @c Emacs 19 feature | |
1511 @defun file-relative-name filename directory | |
1512 This function does the inverse of expansion---it tries to return a | |
1513 relative name which is equivalent to @var{filename} when interpreted | |
1514 relative to @var{directory}. (If such a relative name would be longer | |
1515 than the absolute name, it returns the absolute name instead.) | |
1516 | |
1517 @example | |
1518 (file-relative-name "/foo/bar" "/foo/") | |
1519 @result{} "bar") | |
1520 (file-relative-name "/foo/bar" "/hack/") | |
1521 @result{} "/foo/bar") | |
1522 @end example | |
1523 @end defun | |
1524 | |
1525 @defvar default-directory | |
1526 The value of this buffer-local variable is the default directory for the | |
1527 current buffer. It should be an absolute directory name; it may start | |
1528 with @samp{~}. This variable is local in every buffer. | |
1529 | |
1530 @code{expand-file-name} uses the default directory when its second | |
1531 argument is @code{nil}. | |
1532 | |
1533 On Unix systems, the value is always a string ending with a slash. | |
1534 | |
1535 @example | |
1536 @group | |
1537 default-directory | |
1538 @result{} "/user/lewis/manual/" | |
1539 @end group | |
1540 @end example | |
1541 @end defvar | |
1542 | |
1543 @defun substitute-in-file-name filename | |
1544 This function replaces environment variables references in | |
1545 @var{filename} with the environment variable values. Following standard | |
1546 Unix shell syntax, @samp{$} is the prefix to substitute an environment | |
1547 variable value. | |
1548 | |
1549 The environment variable name is the series of alphanumeric characters | |
1550 (including underscores) that follow the @samp{$}. If the character following | |
1551 the @samp{$} is a @samp{@{}, then the variable name is everything up to the | |
1552 matching @samp{@}}. | |
1553 | |
1554 @c Wordy to avoid overfull hbox. --rjc 15mar92 | |
1555 Here we assume that the environment variable @code{HOME}, which holds | |
1556 the user's home directory name, has value @samp{/xcssun/users/rms}. | |
1557 | |
1558 @example | |
1559 @group | |
1560 (substitute-in-file-name "$HOME/foo") | |
1561 @result{} "/xcssun/users/rms/foo" | |
1562 @end group | |
1563 @end example | |
1564 | |
1565 If a @samp{~} or a @samp{/} appears following a @samp{/}, after | |
1566 substitution, everything before the following @samp{/} is discarded: | |
1567 | |
1568 @example | |
1569 @group | |
1570 (substitute-in-file-name "bar/~/foo") | |
1571 @result{} "~/foo" | |
1572 @end group | |
1573 @group | |
1574 (substitute-in-file-name "/usr/local/$HOME/foo") | |
1575 @result{} "/xcssun/users/rms/foo" | |
1576 @end group | |
1577 @end example | |
1578 | |
1579 On VMS, @samp{$} substitution is not done, so this function does nothing | |
1580 on VMS except discard superfluous initial components as shown above. | |
1581 @end defun | |
1582 | |
1583 @node Unique File Names | |
1584 @subsection Generating Unique File Names | |
1585 | |
1586 Some programs need to write temporary files. Here is the usual way to | |
1587 construct a name for such a file: | |
1588 | |
1589 @example | |
1590 (make-temp-name (concat "/tmp/" @var{name-of-application})) | |
1591 @end example | |
1592 | |
1593 @noindent | |
1594 Here we use the directory @file{/tmp/} because that is the standard | |
1595 place on Unix for temporary files. The job of @code{make-temp-name} is | |
1596 to prevent two different users or two different jobs from trying to use | |
1597 the same name. | |
1598 | |
1599 @defun make-temp-name string | |
1600 This function generates string that can be used as a unique name. The | |
1601 name starts with the prefix @var{string}, and ends with a number that | |
1602 is different in each Emacs job. | |
1603 | |
1604 @example | |
1605 @group | |
1606 (make-temp-name "/tmp/foo") | |
1607 @result{} "/tmp/foo021304" | |
1608 @end group | |
1609 @end example | |
1610 | |
1611 To prevent conflicts among different libraries running in the same | |
1612 Emacs, each Lisp program that uses @code{make-temp-name} should have its | |
1613 own @var{string}. The number added to the end of the name distinguishes | |
1614 between the same application running in different Emacs jobs. | |
1615 @end defun | |
1616 | |
1617 @node File Name Completion | |
1618 @subsection File Name Completion | |
1619 @cindex file name completion subroutines | |
1620 @cindex completion, file name | |
1621 | |
1622 This section describes low-level subroutines for completing a file | |
1623 name. For other completion functions, see @ref{Completion}. | |
1624 | |
1625 @defun file-name-all-completions partial-filename directory | |
1626 This function returns a list of all possible completions for a file | |
1627 whose name starts with @var{partial-filename} in directory | |
1628 @var{directory}. The order of the completions is the order of the files | |
1629 in the directory, which is unpredictable and conveys no useful | |
1630 information. | |
1631 | |
1632 The argument @var{partial-filename} must be a file name containing no | |
1633 directory part and no slash. The current buffer's default directory is | |
1634 prepended to @var{directory}, if @var{directory} is not absolute. | |
1635 | |
1636 In the following example, suppose that the current default directory, | |
1637 @file{~rms/lewis}, has five files whose names begin with @samp{f}: | |
1638 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and | |
1639 @file{file.c.~2~}.@refill | |
1640 | |
1641 @example | |
1642 @group | |
1643 (file-name-all-completions "f" "") | |
1644 @result{} ("foo" "file~" "file.c.~2~" | |
1645 "file.c.~1~" "file.c") | |
1646 @end group | |
1647 | |
1648 @group | |
1649 (file-name-all-completions "fo" "") | |
1650 @result{} ("foo") | |
1651 @end group | |
1652 @end example | |
1653 @end defun | |
1654 | |
1655 @defun file-name-completion filename directory | |
1656 This function completes the file name @var{filename} in directory | |
1657 @var{directory}. It returns the longest prefix common to all file names | |
1658 in directory @var{directory} that start with @var{filename}. | |
1659 | |
1660 If only one match exists and @var{filename} matches it exactly, the | |
1661 function returns @code{t}. The function returns @code{nil} if directory | |
1662 @var{directory} contains no name starting with @var{filename}. | |
1663 | |
1664 In the following example, suppose that the current default directory | |
1665 has five files whose names begin with @samp{f}: @file{foo}, | |
1666 @file{file~}, @file{file.c}, @file{file.c.~1~}, and | |
1667 @file{file.c.~2~}.@refill | |
1668 | |
1669 @example | |
1670 @group | |
1671 (file-name-completion "fi" "") | |
1672 @result{} "file" | |
1673 @end group | |
1674 | |
1675 @group | |
1676 (file-name-completion "file.c.~1" "") | |
1677 @result{} "file.c.~1~" | |
1678 @end group | |
1679 | |
1680 @group | |
1681 (file-name-completion "file.c.~1~" "") | |
1682 @result{} t | |
1683 @end group | |
1684 | |
1685 @group | |
1686 (file-name-completion "file.c.~3" "") | |
1687 @result{} nil | |
1688 @end group | |
1689 @end example | |
1690 @end defun | |
1691 | |
1692 @defopt completion-ignored-extensions | |
1693 @code{file-name-completion} usually ignores file names that end in any | |
1694 string in this list. It does not ignore them when all the possible | |
1695 completions end in one of these suffixes or when a buffer showing all | |
1696 possible completions is displayed.@refill | |
1697 | |
1698 A typical value might look like this: | |
1699 | |
1700 @example | |
1701 @group | |
1702 completion-ignored-extensions | |
1703 @result{} (".o" ".elc" "~" ".dvi") | |
1704 @end group | |
1705 @end example | |
1706 @end defopt | |
1707 | |
1708 @node Contents of Directories | |
1709 @section Contents of Directories | |
1710 @cindex directory-oriented functions | |
1711 @cindex file names in directory | |
1712 | |
1713 A directory is a kind of file that contains other files entered under | |
1714 various names. Directories are a feature of the file system. | |
1715 | |
1716 Emacs can list the names of the files in a directory as a Lisp list, | |
1717 or display the names in a buffer using the @code{ls} shell command. In | |
1718 the latter case, it can optionally display information about each file, | |
1719 depending on the options passed to the @code{ls} command. | |
1720 | |
1721 @defun directory-files directory &optional full-name match-regexp nosort | |
1722 This function returns a list of the names of the files in the directory | |
1723 @var{directory}. By default, the list is in alphabetical order. | |
1724 | |
1725 If @var{full-name} is non-@code{nil}, the function returns the files' | |
1726 absolute file names. Otherwise, it returns the names relative to | |
1727 the specified directory. | |
1728 | |
1729 If @var{match-regexp} is non-@code{nil}, this function returns only | |
1730 those file names that contain a match for that regular expression---the | |
1731 other file names are excluded from the list. | |
1732 | |
1733 @c Emacs 19 feature | |
1734 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort | |
1735 the list, so you get the file names in no particular order. Use this if | |
1736 you want the utmost possible speed and don't care what order the files | |
1737 are processed in. If the order of processing is visible to the user, | |
1738 then the user will probably be happier if you do sort the names. | |
1739 | |
1740 @example | |
1741 @group | |
1742 (directory-files "~lewis") | |
1743 @result{} ("#foo#" "#foo.el#" "." ".." | |
1744 "dired-mods.el" "files.texi" | |
1745 "files.texi.~1~") | |
1746 @end group | |
1747 @end example | |
1748 | |
1749 An error is signaled if @var{directory} is not the name of a directory | |
1750 that can be read. | |
1751 @end defun | |
1752 | |
1753 @defun file-name-all-versions file dirname | |
1754 This function returns a list of all versions of the file named | |
1755 @var{file} in directory @var{dirname}. | |
1756 @end defun | |
1757 | |
1758 @defun insert-directory file switches &optional wildcard full-directory-p | |
1759 This function inserts a directory listing for directory @var{dir}, | |
1760 formatted with @code{ls} according to @var{switches}. It leaves point | |
1761 after the inserted text. | |
1762 | |
1763 The argument @var{dir} may be either a directory name or a file | |
1764 specification including wildcard characters. If @var{wildcard} is | |
1765 non-@code{nil}, that means treat @var{file} as a file specification with | |
1766 wildcards. | |
1767 | |
1768 If @var{full-directory-p} is non-@code{nil}, that means @var{file} is a | |
1769 directory and switches do not contain @samp{d}, so that a full listing | |
1770 is expected. | |
1771 | |
1772 This function works by running a directory listing program whose name is | |
1773 in the variable @code{insert-directory-program}. If @var{wildcard} is | |
1774 non-@code{nil}, it also runs the shell specified by | |
1775 @code{shell-file-name}, to expand the wildcards. | |
1776 @end defun | |
1777 | |
1778 @defvar insert-directory-program | |
1779 This variable's value is the program to run to generate a directory listing | |
1780 for the function @code{insert-directory}. | |
1781 @end defvar | |
1782 | |
1783 @node Create/Delete Dirs | |
1784 @section Creating and Deleting Directories | |
1785 @c Emacs 19 features | |
1786 | |
1787 @defun make-directory dirname | |
1788 This function creates a directory named @var{dirname}. | |
1789 @end defun | |
1790 | |
1791 @defun delete-directory dirname | |
1792 This function deletes the directory named @var{dirname}. The function | |
1793 @code{delete-file} does not work for files that are directories; you | |
1794 must use @code{delete-directory} in that case. | |
1795 @end defun | |
1796 | |
1797 @node Magic File Names | |
1798 @section Making Certain File Names ``Magic'' | |
1799 @cindex magic file names | |
1800 | |
1801 @c Emacs 19 feature | |
1802 You can implement special handling for certain file names. This is | |
1803 called making those names @dfn{magic}. You must supply a regular | |
1804 expression to define the class of names (all those which match the | |
1805 regular expression), plus a handler that implements all the primitive | |
1806 Emacs file operations for file names that do match. | |
1807 | |
1808 The value of @code{file-name-handler-alist} is a list of handlers, | |
1809 together with regular expressions that determine when to apply each | |
1810 handler. Each element has this form: | |
1811 | |
1812 @example | |
1813 (@var{regexp} . @var{handler}) | |
1814 @end example | |
1815 | |
1816 @noindent | |
1817 All the Emacs primitives for file access and file name transformation | |
1818 check the given file name against @code{file-name-handler-alist}. If | |
1819 the file name matches @var{regexp}, the primitives handle that file by | |
1820 calling @var{handler}. | |
1821 | |
1822 The first argument given to @var{handler} is the name of the primitive; | |
1823 the remaining arguments are the arguments that were passed to that | |
1824 operation. (The first of these arguments is typically the file name | |
1825 itself.) For example, if you do this: | |
1826 | |
1827 @example | |
1828 (file-exists-p @var{filename}) | |
1829 @end example | |
1830 | |
1831 @noindent | |
1832 and @var{filename} has handler @var{handler}, then @var{handler} is | |
1833 called like this: | |
1834 | |
1835 @example | |
1836 (funcall @var{handler} 'file-exists-p @var{filename}) | |
1837 @end example | |
1838 | |
1839 Here are the operations that you can handle for a magic file name: | |
1840 | |
1841 @noindent | |
1842 @code{add-name-to-file}, @code{copy-file}, @code{delete-directory}, | |
1843 @code{delete-file},@* | |
1844 @code{directory-file-name}, | |
1845 @code{diff-latest-backup-file}, @code{directory-files}, | |
1846 @code{dired-compress-file}, @code{dired-uncache}, | |
1847 @code{expand-file-name},@* | |
1848 @code{file-accessible-directory-p}, | |
1849 @code{file-attributes}, @code{file-directory-p}, | |
1850 @code{file-executable-p}, @code{file-exists-p}, @code{file-local-copy}, | |
1851 @code{file-modes}, @code{file-name-all-completions}, | |
1852 @code{file-name-as-directory}, @code{file-name-completion}, | |
1853 @code{file-name-directory}, @code{file-name-nondirectory}, | |
1854 @code{file-name-sans-versions}, @code{file-newer-than-file-p}, | |
1855 @code{file-readable-p}, @code{file-symlink-p}, @code{file-truename}, | |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1856 @code{file-writable-p},@* |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1857 @code{insert-directory}, |
6555 | 1858 @code{insert-file-contents}, @code{load}, @code{make-directory}, |
1859 @code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes}, | |
1860 @code{set-visited-file-modtime}, @code{unhandled-file-name-directory}, | |
1861 @code{verify-visited-file-modtime}, @code{write-region}. | |
1862 | |
1863 The handler function must handle all of the above operations, and | |
1864 possibly others to be added in the future. Therefore, it should always | |
1865 reinvoke the ordinary Lisp primitive when it receives an operation it | |
1866 does not recognize. Here's one way to do this: | |
1867 | |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1868 @smallexample |
6555 | 1869 (defun my-file-handler (operation &rest args) |
1870 ;; @r{First check for the specific operations} | |
1871 ;; @r{that we have special handling for.} | |
1872 (cond ((eq operation 'insert-file-contents) @dots{}) | |
1873 ((eq operation 'write-region) @dots{}) | |
1874 @dots{} | |
1875 ;; @r{Handle any operation we don't know about.} | |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1876 (t (let ((inhibit-file-name-handlers |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1877 (cons 'ange-ftp-file-handler |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1878 (and (eq inhibit-file-name-operation operation) |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1879 inhibit-file-name-handlers))) |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1880 (inhibit-file-name-operation operation)) |
6555 | 1881 (apply operation args))))) |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1882 @end smallexample |
6555 | 1883 |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1884 When a handler function decides to call the ordinary Emacs primitive for |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1885 the operation at hand, it needs to prevent the primitive from calling |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1886 the same handler once again, thus leading to an infinite recursion. The |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1887 example above shows how to do this, with the variables |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1888 @code{inhibit-file-name-handlers} and |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1889 @code{inhibit-file-name-operation}. Be careful to use them exactly as |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1890 shown above; the details are crucial for proper behavior in the case of |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1891 multiple handlers, and for operations that have two file names that may |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1892 each have handlers. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1893 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1894 @defvar inhibit-file-name-handlers |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1895 This variable holds a list of handlers whose use is presently inhibited |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1896 for a certain operation. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1897 @end defvar |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1898 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1899 @defvar inhibit-file-name-operation |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1900 The operation for which certain handlers are presently inhibited. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1901 @end defvar |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1902 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1903 @defun find-file-name-handler file operation |
6555 | 1904 This function returns the handler function for file name @var{file}, or |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1905 @code{nil} if there is none. The argument @var{operation} should be the |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1906 operation to be performed on the file---the value you will pass to the |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1907 handler as its first argument when you call it. The operation is needed |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1908 for comparison with @code{inhibit-file-name-operation}. |
6555 | 1909 @end defun |
1910 | |
1911 @defun file-local-copy filename | |
1912 This function copies file @var{filename} to the local site, if it isn't | |
1913 there already. If @var{filename} specifies a ``magic'' file name which | |
1914 programs outside Emacs cannot directly read or write, this copies the | |
1915 contents to an ordinary file and returns that file's name. | |
1916 | |
1917 If @var{filename} is an ordinary file name, not magic, then this function | |
1918 does nothing and returns @code{nil}. | |
1919 @end defun | |
1920 | |
1921 @defun unhandled-file-name-directory filename | |
1922 This function returns the name of a directory that is not magic. | |
1923 It uses the directory part of @var{filename} if that is not magic. | |
1924 Otherwise, it asks the handler what to do. | |
1925 | |
1926 This is useful for running a subprocess; every subprocess must have a | |
1927 non-magic directory to serve as its current directory, and this function | |
1928 is a good way to come up with one. | |
1929 @end defun | |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1930 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1931 @node Files and MS-DOS |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1932 @section Files and MS-DOS |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1933 @cindex MS-DOS file types |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1934 @cindex file types on MS-DOS |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1935 @cindex text files and binary files |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1936 @cindex binary files and text files |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1937 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1938 Emacs on MS-DOS makes a distinction between text files and binary |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1939 files. This is necessary because ordinary text files on MS-DOS use two |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1940 characters between lines: carriage-return and linefeed. Emacs expects |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1941 just a newline character (a linefeed) between lines. When Emacs reads |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1942 or writes a text file on MS-DOS, it needs to convert the line |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1943 separators. This means it needs to know which files are text files and |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1944 which are binary. It makes this decision when visiting a file, and |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1945 records the decision in the variable @code{buffer-file-type} for when |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1946 the file is saved. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1947 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1948 @defvar buffer-file-type |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1949 This variable, automatically local in each buffer, records the file type |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1950 of the buffer's visited file. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1951 @end defvar |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1952 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1953 @defun find-buffer-file-type filename |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1954 This function determines whether file @var{filename} is a text file |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1955 or a binary file. It returns @code{nil} for text, @code{t} for binary. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1956 @end defun |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1957 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1958 @defopt file-name-buffer-file-type-alist |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1959 This variable holds an alist for distinguishing text files from binary |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1960 files. Each element has the form (@var{regexp} . @var{type}), where |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1961 @var{regexp} is matched against the file name, and @var{type} may be is |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1962 @code{nil} for text, @code{t} for binary, or a function to call to |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1963 compute which. If it is a function, then it is called with a single |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1964 argument (the file name) and should return @code{t} or @code{nil}. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1965 @end defopt |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1966 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1967 @defopt default-buffer-file-type |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1968 This variable specifies the default file type for files whose names |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1969 don't indicate anything in particular. Its value should be @code{nil} |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1970 for text, or @code{t} for binary. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1971 @end defopt |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1972 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1973 @deffn Command find-file-text filename |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1974 Like @code{find-file}, but treat the file as text regardless of its name. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1975 @end deffn |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1976 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1977 @deffn Command find-file-binary filename |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1978 Like @code{find-file}, but treat the file as binary regardless of its |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1979 name. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1980 @end deffn |