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