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