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