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