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