1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Help Functions, Next: Obsoleteness, Prev: Describing Characters, Up: Documentation
58 XEmacs provides a variety of on-line help functions, all accessible
59 to the user as subcommands of the prefix `C-h', or on some keyboards,
60 `help'. For more information about them, see *Note Help: (emacs)Help.
61 Here we describe some program-level interfaces to the same information.
63 - Command: apropos regexp &optional do-all predicate
64 This function finds all symbols whose names contain a match for the
65 regular expression REGEXP, and returns a list of them (*note
66 Regular Expressions::). It also displays the symbols in a buffer
67 named `*Help*', each with a one-line description.
69 If DO-ALL is non-`nil', then `apropos' also shows key bindings for
70 the functions that are found.
72 If PREDICATE is non-`nil', it should be a function to be called on
73 each symbol that has matched REGEXP. Only symbols for which
74 PREDICATE returns a non-`nil' value are listed or displayed.
76 In the first of the following examples, `apropos' finds all the
77 symbols with names containing `exec'. In the second example, it
78 finds and returns only those symbols that are also commands. (We
79 don't show the output that results in the `*Help*' buffer.)
82 => (Buffer-menu-execute command-execute exec-directory
83 exec-path execute-extended-command execute-kbd-macro
84 executing-kbd-macro executing-macro)
86 (apropos "exec" nil 'commandp)
87 => (Buffer-menu-execute execute-extended-command)
89 `apropos' is used by various user-level commands, such as `C-h a'
90 (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A'
91 (`command-apropos'), which does an apropos over only those
92 functions which are user commands. `command-apropos' calls
93 `apropos', specifying a PREDICATE to restrict the output to
94 symbols that are commands. The call to `apropos' looks like this:
96 (apropos string t 'commandp)
99 The value of this variable is a local keymap for characters
100 following the Help key, `C-h'.
102 - Prefix Command: help-command
103 This symbol is not a function; its function definition is actually
104 the keymap known as `help-map'. It is defined in `help.el' as
107 (define-key global-map "\C-h" 'help-command)
108 (fset 'help-command help-map)
110 - Function: print-help-return-message &optional function
111 This function builds a string that explains how to restore the
112 previous state of the windows after a help command. After
113 building the message, it applies FUNCTION to it if FUNCTION is
114 non-`nil'. Otherwise it calls `message' to display it in the echo
117 This function expects to be called inside a
118 `with-output-to-temp-buffer' special form, and expects
119 `standard-output' to have the value bound by that special form.
120 For an example of its use, see the long example in *Note Accessing
123 - Variable: help-char
124 The value of this variable is the help character--the character
125 that XEmacs recognizes as meaning Help. By default, it is the
126 character `?\^H' (ASCII 8), which is `C-h'. When XEmacs reads this
127 character, if `help-form' is non-`nil' Lisp expression, it
128 evaluates that expression, and displays the result in a window if
131 `help-char' can be a character or a key description such as `help'
134 Usually the value of `help-form''s value is `nil'. Then the help
135 character has no special meaning at the level of command input, and
136 it becomes part of a key sequence in the normal way. The standard
137 key binding of `C-h' is a prefix key for several general-purpose
140 The help character is special after prefix keys, too. If it has no
141 binding as a subcommand of the prefix key, it runs
142 `describe-prefix-bindings', which displays a list of all the
143 subcommands of the prefix key.
145 - Variable: help-form
146 If this variable is non-`nil', its value is a form to evaluate
147 whenever the character `help-char' is read. If evaluating the form
148 produces a string, that string is displayed.
150 A command that calls `next-command-event' or `next-event' probably
151 should bind `help-form' to a non-`nil' expression while it does
152 input. (The exception is when `C-h' is meaningful input.)
153 Evaluating this expression should result in a string that explains
154 what the input is for and how to enter it properly.
156 Entry to the minibuffer binds this variable to the value of
157 `minibuffer-help-form' (*note Minibuffer Misc::).
159 - Variable: prefix-help-command
160 This variable holds a function to print help for a prefix
161 character. The function is called when the user types a prefix
162 key followed by the help character, and the help character has no
163 binding after that prefix. The variable's default value is
164 `describe-prefix-bindings'.
166 - Command: describe-prefix-bindings
167 This function calls `describe-bindings' to display a list of all
168 the subcommands of the prefix key of the most recent key sequence.
169 The prefix described consists of all but the last event of that
170 key sequence. (The last event is, presumably, the help character.)
172 The following two functions are found in the library `helper'. They
173 are for modes that want to provide help without relinquishing control,
174 such as the "electric" modes. You must load that library with
175 `(require 'helper)' in order to use them. Their names begin with
176 `Helper' to distinguish them from the ordinary help functions.
178 - Command: Helper-describe-bindings
179 This command pops up a window displaying a help buffer containing a
180 listing of all of the key bindings from both the local and global
181 keymaps. It works by calling `describe-bindings'.
183 - Command: Helper-help
184 This command provides help for the current mode. It prompts the
185 user in the minibuffer with the message `Help (Type ? for further
186 options)', and then provides assistance in finding out what the key
187 bindings are, and what the mode is intended for. It returns `nil'.
189 This can be customized by changing the map `Helper-help-map'.
192 File: lispref.info, Node: Obsoleteness, Prev: Help Functions, Up: Documentation
197 As you add functionality to a package, you may at times want to
198 replace an older function with a new one. To preserve compatibility
199 with existing code, the older function needs to still exist; but users
200 of that function should be told to use the newer one instead. XEmacs
201 Lisp lets you mark a function or variable as "obsolete", and indicate
202 what should be used instead.
204 - Command: make-obsolete function new
205 This function indicates that FUNCTION is an obsolete function, and
206 the function NEW should be used instead. The byte compiler will
207 issue a warning to this effect when it encounters a usage of the
208 older function, and the help system will also note this in the
209 function's documentation. NEW can also be a string (if there is
210 not a single function with the same functionality any more), and
211 should be a descriptive statement, such as "use FOO or BAR
212 instead" or "this function is unnecessary".
214 - Command: make-obsolete-variable variable new
215 This is like `make-obsolete' but is for variables instead of
218 - Function: define-obsolete-function-alias oldfun newfun
219 This function combines `make-obsolete' and `define-function',
220 declaring OLDFUN to be an obsolete variant of NEWFUN and defining
221 OLDFUN as an alias for NEWFUN.
223 - Function: define-obsolete-variable-alias oldvar newvar
224 This is like `define-obsolete-function-alias' but for variables.
226 Note that you should not normally put obsoleteness information
227 explicitly in a function or variable's doc string. The obsoleteness
228 information that you specify using the above functions will be displayed
229 whenever the doc string is displayed, and by adding it explicitly the
230 result is redundancy.
232 Also, if an obsolete function is substantially the same as a newer
233 one but is not actually an alias, you should consider omitting the doc
234 string entirely (use a null string `""' as the doc string). That way,
235 the user is told about the obsoleteness and is forced to look at the
236 documentation of the new function, making it more likely that he will
237 use the new function.
239 - Function: function-obsoleteness-doc function
240 If FUNCTION is obsolete, this function returns a string describing
241 this. This is the message that is printed out during byte
242 compilation or in the function's documentation. If FUNCTION is
243 not obsolete, `nil' is returned.
245 - Function: variable-obsoleteness-doc variable
246 This is like `function-obsoleteness-doc' but for variables.
248 The obsoleteness information is stored internally by putting a
249 property `byte-obsolete-info' (for functions) or
250 `byte-obsolete-variable' (for variables) on the symbol that specifies
251 the obsolete function or variable. For more information, see the
252 implementation of `make-obsolete' and `make-obsolete-variable' in
253 `lisp/bytecomp/bytecomp-runtime.el'.
256 File: lispref.info, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top
261 In XEmacs, you can find, create, view, save, and otherwise work with
262 files and file directories. This chapter describes most of the
263 file-related functions of XEmacs Lisp, but a few others are described in
264 *Note Buffers::, and those related to backups and auto-saving are
265 described in *Note Backups and Auto-Saving::.
267 Many of the file functions take one or more arguments that are file
268 names. A file name is actually a string. Most of these functions
269 expand file name arguments using `expand-file-name', so that `~' is
270 handled correctly, as are relative file names (including `../'). These
271 functions don't recognize environment variable substitutions such as
272 `$HOME'. *Note File Name Expansion::.
276 * Visiting Files:: Reading files into Emacs buffers for editing.
277 * Saving Buffers:: Writing changed buffers back into files.
278 * Reading from Files:: Reading files into buffers without visiting.
279 * Writing to Files:: Writing new files from parts of buffers.
280 * File Locks:: Locking and unlocking files, to prevent
281 simultaneous editing by two people.
282 * Information about Files:: Testing existence, accessibility, size of files.
283 * Changing File Attributes:: Renaming files, changing protection, etc.
284 * File Names:: Decomposing and expanding file names.
285 * Contents of Directories:: Getting a list of the files in a directory.
286 * Create/Delete Dirs:: Creating and Deleting Directories.
287 * Magic File Names:: Defining "magic" special handling
288 for certain file names.
289 * Partial Files:: Treating a section of a buffer as a file.
290 * Format Conversion:: Conversion to and from various file formats.
291 * Files and MS-DOS:: Distinguishing text and binary files on MS-DOS.
294 File: lispref.info, Node: Visiting Files, Next: Saving Buffers, Up: Files
299 Visiting a file means reading a file into a buffer. Once this is
300 done, we say that the buffer is "visiting" that file, and call the file
301 "the visited file" of the buffer.
303 A file and a buffer are two different things. A file is information
304 recorded permanently in the computer (unless you delete it). A buffer,
305 on the other hand, is information inside of XEmacs that will vanish at
306 the end of the editing session (or when you kill the buffer). Usually,
307 a buffer contains information that you have copied from a file; then we
308 say the buffer is visiting that file. The copy in the buffer is what
309 you modify with editing commands. Such changes to the buffer do not
310 change the file; therefore, to make the changes permanent, you must
311 "save" the buffer, which means copying the altered buffer contents back
314 In spite of the distinction between files and buffers, people often
315 refer to a file when they mean a buffer and vice-versa. Indeed, we say,
316 "I am editing a file," rather than, "I am editing a buffer that I will
317 soon save as a file of the same name." Humans do not usually need to
318 make the distinction explicit. When dealing with a computer program,
319 however, it is good to keep the distinction in mind.
323 * Visiting Functions:: The usual interface functions for visiting.
324 * Subroutines of Visiting:: Lower-level subroutines that they use.
327 File: lispref.info, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files
329 Functions for Visiting Files
330 ----------------------------
332 This section describes the functions normally used to visit files.
333 For historical reasons, these functions have names starting with
334 `find-' rather than `visit-'. *Note Buffer File Name::, for functions
335 and variables that access the visited file name of a buffer or that
336 find an existing buffer by its visited file name.
338 In a Lisp program, if you want to look at the contents of a file but
339 not alter it, the fastest way is to use `insert-file-contents' in a
340 temporary buffer. Visiting the file is not necessary and takes longer.
341 *Note Reading from Files::.
343 - Command: find-file filename
344 This command selects a buffer visiting the file FILENAME, using an
345 existing buffer if there is one, and otherwise creating a new
346 buffer and reading the file into it. It also returns that buffer.
348 The body of the `find-file' function is very simple and looks like
351 (switch-to-buffer (find-file-noselect filename))
353 (See `switch-to-buffer' in *Note Displaying Buffers::.)
355 When `find-file' is called interactively, it prompts for FILENAME
358 - Function: find-file-noselect filename &optional nowarn
359 This function is the guts of all the file-visiting functions. It
360 finds or creates a buffer visiting the file FILENAME, and returns
361 it. It uses an existing buffer if there is one, and otherwise
362 creates a new buffer and reads the file into it. You may make the
363 buffer current or display it in a window if you wish, but this
364 function does not do so.
366 When `find-file-noselect' uses an existing buffer, it first
367 verifies that the file has not changed since it was last visited or
368 saved in that buffer. If the file has changed, then this function
369 asks the user whether to reread the changed file. If the user says
370 `yes', any changes previously made in the buffer are lost.
372 If `find-file-noselect' needs to create a buffer, and there is no
373 file named FILENAME, it displays the message `New file' in the
374 echo area, and leaves the buffer empty.
376 If NOWARN is non-`nil', various warnings that XEmacs normally
377 gives (e.g. if another buffer is already visiting FILENAME but
378 FILENAME has been removed from disk since that buffer was created)
381 The `find-file-noselect' function calls `after-find-file' after
382 reading the file (*note Subroutines of Visiting::). That function
383 sets the buffer major mode, parses local variables, warns the user
384 if there exists an auto-save file more recent than the file just
385 visited, and finishes by running the functions in
388 The `find-file-noselect' function returns the buffer that is
389 visiting the file FILENAME.
391 (find-file-noselect "/etc/fstab")
394 - Command: find-file-other-window filename
395 This command selects a buffer visiting the file FILENAME, but does
396 so in a window other than the selected window. It may use another
397 existing window or split a window; see *Note Displaying Buffers::.
399 When this command is called interactively, it prompts for FILENAME.
401 - Command: find-file-read-only filename
402 This command selects a buffer visiting the file FILENAME, like
403 `find-file', but it marks the buffer as read-only. *Note Read
404 Only Buffers::, for related functions and variables.
406 When this command is called interactively, it prompts for FILENAME.
408 - Command: view-file filename &optional other-window-p
409 This command visits FILENAME in View mode, and displays it in a
410 recursive edit, returning to the previous buffer when done. View
411 mode is a mode that allows you to skim rapidly through the file
412 but does not let you modify it. Entering View mode runs the
413 normal hook `view-mode-hook'. *Note Hooks::.
415 When `view-file' is called interactively, it prompts for FILENAME.
417 With non-`nil' prefix arg OTHER-WINDOW-P, visit FILENAME in
420 - Variable: find-file-hooks
421 The value of this variable is a list of functions to be called
422 after a file is visited. The file's local-variables specification
423 (if any) will have been processed before the hooks are run. The
424 buffer visiting the file is current when the hook functions are
427 This variable works just like a normal hook, but we think that
428 renaming it would not be advisable.
430 - Variable: find-file-not-found-hooks
431 The value of this variable is a list of functions to be called when
432 `find-file' or `find-file-noselect' is passed a nonexistent file
433 name. `find-file-noselect' calls these functions as soon as it
434 detects a nonexistent file. It calls them in the order of the
435 list, until one of them returns non-`nil'. `buffer-file-name' is
438 This is not a normal hook because the values of the functions are
439 used and they may not all be called.
442 File: lispref.info, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files
444 Subroutines of Visiting
445 -----------------------
447 The `find-file-noselect' function uses the `create-file-buffer' and
448 `after-find-file' functions as subroutines. Sometimes it is useful to
451 - Function: create-file-buffer filename
452 This function creates a suitably named buffer for visiting
453 FILENAME, and returns it. It uses FILENAME (sans directory) as
454 the name if that name is free; otherwise, it appends a string such
455 as `<2>' to get an unused name. See also *Note Creating Buffers::.
457 *Please note:* `create-file-buffer' does _not_ associate the new
458 buffer with a file and does not select the buffer. It also does
459 not use the default major mode.
461 (create-file-buffer "foo")
463 (create-file-buffer "foo")
465 (create-file-buffer "foo")
468 This function is used by `find-file-noselect'. It uses
469 `generate-new-buffer' (*note Creating Buffers::).
471 - Function: after-find-file &optional error warn noauto
472 This function sets the buffer major mode, and parses local
473 variables (*note Auto Major Mode::). It is called by
474 `find-file-noselect' and by the default revert function (*note
477 If reading the file got an error because the file does not exist,
478 but its directory does exist, the caller should pass a non-`nil'
479 value for ERROR. In that case, `after-find-file' issues a warning:
480 `(New File)'. For more serious errors, the caller should usually
481 not call `after-find-file'.
483 If WARN is non-`nil', then this function issues a warning if an
484 auto-save file exists and is more recent than the visited file.
486 If NOAUTO is non-`nil', then this function does not turn on
487 auto-save mode; otherwise, it does.
489 The last thing `after-find-file' does is call all the functions in
493 File: lispref.info, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files
498 When you edit a file in XEmacs, you are actually working on a buffer
499 that is visiting that file--that is, the contents of the file are
500 copied into the buffer and the copy is what you edit. Changes to the
501 buffer do not change the file until you "save" the buffer, which means
502 copying the contents of the buffer into the file.
504 - Command: save-buffer &optional backup-option
505 This function saves the contents of the current buffer in its
506 visited file if the buffer has been modified since it was last
507 visited or saved. Otherwise it does nothing.
509 `save-buffer' is responsible for making backup files. Normally,
510 BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only
511 if this is the first save since visiting the file. Other values
512 for BACKUP-OPTION request the making of backup files in other
515 * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the
516 `save-buffer' function marks this version of the file to be
517 backed up when the buffer is next saved.
519 * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the
520 `save-buffer' function unconditionally backs up the previous
521 version of the file before saving it.
523 - Command: save-some-buffers &optional save-silently-p exiting
524 This command saves some modified file-visiting buffers. Normally
525 it asks the user about each buffer. But if SAVE-SILENTLY-P is
526 non-`nil', it saves all the file-visiting buffers without querying
529 The optional EXITING argument, if non-`nil', requests this
530 function to offer also to save certain other buffers that are not
531 visiting files. These are buffers that have a non-`nil' local
532 value of `buffer-offer-save'. (A user who says yes to saving one
533 of these is asked to specify a file name to use.) The
534 `save-buffers-kill-emacs' function passes a non-`nil' value for
537 - Variable: buffer-offer-save
538 When this variable is non-`nil' in a buffer, XEmacs offers to save
539 the buffer on exit even if the buffer is not visiting a file. The
540 variable is automatically local in all buffers. Normally, Mail
541 mode (used for editing outgoing mail) sets this to `t'.
543 - Command: write-file filename
544 This function writes the current buffer into file FILENAME, makes
545 the buffer visit that file, and marks it not modified. Then it
546 renames the buffer based on FILENAME, appending a string like `<2>'
547 if necessary to make a unique buffer name. It does most of this
548 work by calling `set-visited-file-name' and `save-buffer'.
550 - Variable: write-file-hooks
551 The value of this variable is a list of functions to be called
552 before writing out a buffer to its visited file. If one of them
553 returns non-`nil', the file is considered already written and the
554 rest of the functions are not called, nor is the usual code for
555 writing the file executed.
557 If a function in `write-file-hooks' returns non-`nil', it is
558 responsible for making a backup file (if that is appropriate). To
559 do so, execute the following code:
561 (or buffer-backed-up (backup-buffer))
563 You might wish to save the file modes value returned by
564 `backup-buffer' and use that to set the mode bits of the file that
565 you write. This is what `save-buffer' normally does.
567 Even though this is not a normal hook, you can use `add-hook' and
568 `remove-hook' to manipulate the list. *Note Hooks::.
570 - Variable: local-write-file-hooks
571 This works just like `write-file-hooks', but it is intended to be
572 made local to particular buffers. It's not a good idea to make
573 `write-file-hooks' local to a buffer--use this variable instead.
575 The variable is marked as a permanent local, so that changing the
576 major mode does not alter a buffer-local value. This is
577 convenient for packages that read "file" contents in special ways,
578 and set up hooks to save the data in a corresponding way.
580 - Variable: write-contents-hooks
581 This works just like `write-file-hooks', but it is intended for
582 hooks that pertain to the contents of the file, as opposed to
583 hooks that pertain to where the file came from. Such hooks are
584 usually set up by major modes, as buffer-local bindings for this
585 variable. Switching to a new major mode always resets this
588 - Variable: after-save-hook
589 This normal hook runs after a buffer has been saved in its visited
592 - Variable: file-precious-flag
593 If this variable is non-`nil', then `save-buffer' protects against
594 I/O errors while saving by writing the new file to a temporary
595 name instead of the name it is supposed to have, and then renaming
596 it to the intended name after it is clear there are no errors.
597 This procedure prevents problems such as a lack of disk space from
598 resulting in an invalid file.
600 As a side effect, backups are necessarily made by copying. *Note
601 Rename or Copy::. Yet, at the same time, saving a precious file
602 always breaks all hard links between the file you save and other
605 Some modes set this variable non-`nil' locally in particular
608 - User Option: require-final-newline
609 This variable determines whether files may be written out that do
610 _not_ end with a newline. If the value of the variable is `t',
611 then `save-buffer' silently adds a newline at the end of the file
612 whenever the buffer being saved does not already end in one. If
613 the value of the variable is non-`nil', but not `t', then
614 `save-buffer' asks the user whether to add a newline each time the
617 If the value of the variable is `nil', then `save-buffer' doesn't
618 add newlines at all. `nil' is the default value, but a few major
619 modes set it to `t' in particular buffers.
622 File: lispref.info, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files
627 You can copy a file from the disk and insert it into a buffer using
628 the `insert-file-contents' function. Don't use the user-level command
629 `insert-file' in a Lisp program, as that sets the mark.
631 - Function: insert-file-contents filename &optional visit start end
633 This function inserts the contents of file FILENAME into the
634 current buffer after point. It returns a list of the absolute
635 file name and the length of the data inserted. An error is
636 signaled if FILENAME is not the name of a file that can be read.
638 The function `insert-file-contents' checks the file contents
639 against the defined file formats, and converts the file contents if
640 appropriate. *Note Format Conversion::. It also calls the
641 functions in the list `after-insert-file-functions'; see *Note
644 If VISIT is non-`nil', this function additionally marks the buffer
645 as unmodified and sets up various fields in the buffer so that it
646 is visiting the file FILENAME: these include the buffer's visited
647 file name and its last save file modtime. This feature is used by
648 `find-file-noselect' and you probably should not use it yourself.
650 If START and END are non-`nil', they should be integers specifying
651 the portion of the file to insert. In this case, VISIT must be
654 (insert-file-contents filename nil 0 500)
656 inserts the first 500 characters of a file.
658 If the argument REPLACE is non-`nil', it means to replace the
659 contents of the buffer (actually, just the accessible portion)
660 with the contents of the file. This is better than simply
661 deleting the buffer contents and inserting the whole file, because
662 (1) it preserves some marker positions and (2) it puts less data
665 If you want to pass a file name to another process so that another
666 program can read the file, use the function `file-local-copy'; see
667 *Note Magic File Names::.
670 File: lispref.info, Node: Writing to Files, Next: File Locks, Prev: Reading from Files, Up: Files
675 You can write the contents of a buffer, or part of a buffer, directly
676 to a file on disk using the `append-to-file' and `write-region'
677 functions. Don't use these functions to write to files that are being
678 visited; that could cause confusion in the mechanisms for visiting.
680 - Command: append-to-file start end filename
681 This function appends the contents of the region delimited by
682 START and END in the current buffer to the end of file FILENAME.
683 If that file does not exist, it is created. If that file exists
684 it is overwritten. This function returns `nil'.
686 An error is signaled if FILENAME specifies a nonwritable file, or
687 a nonexistent file in a directory where files cannot be created.
689 - Command: write-region start end filename &optional append visit
690 This function writes the region delimited by START and END in the
691 current buffer into the file specified by FILENAME.
693 If START is a string, then `write-region' writes or appends that
694 string, rather than text from the buffer.
696 If APPEND is non-`nil', then the specified text is appended to the
697 existing file contents (if any).
699 If VISIT is `t', then XEmacs establishes an association between
700 the buffer and the file: the buffer is then visiting that file.
701 It also sets the last file modification time for the current
702 buffer to FILENAME's modtime, and marks the buffer as not
703 modified. This feature is used by `save-buffer', but you probably
704 should not use it yourself.
706 If VISIT is a string, it specifies the file name to visit. This
707 way, you can write the data to one file (FILENAME) while recording
708 the buffer as visiting another file (VISIT). The argument VISIT
709 is used in the echo area message and also for file locking; VISIT
710 is stored in `buffer-file-name'. This feature is used to
711 implement `file-precious-flag'; don't use it yourself unless you
712 really know what you're doing.
714 The function `write-region' converts the data which it writes to
715 the appropriate file formats specified by `buffer-file-format'.
716 *Note Format Conversion::. It also calls the functions in the list
717 `write-region-annotate-functions'; see *Note Saving Properties::.
719 Normally, `write-region' displays a message `Wrote file FILENAME'
720 in the echo area. If VISIT is neither `t' nor `nil' nor a string,
721 then this message is inhibited. This feature is useful for
722 programs that use files for internal purposes, files that the user
723 does not need to know about.
726 File: lispref.info, Node: File Locks, Next: Information about Files, Prev: Writing to Files, Up: Files
731 When two users edit the same file at the same time, they are likely
732 to interfere with each other. XEmacs tries to prevent this situation
733 from arising by recording a "file lock" when a file is being modified.
734 XEmacs can then detect the first attempt to modify a buffer visiting a
735 file that is locked by another XEmacs process, and ask the user what to
738 File locks do not work properly when multiple machines can share
739 file systems, such as with NFS. Perhaps a better file locking system
740 will be implemented in the future. When file locks do not work, it is
741 possible for two users to make changes simultaneously, but XEmacs can
742 still warn the user who saves second. Also, the detection of
743 modification of a buffer visiting a file changed on disk catches some
744 cases of simultaneous editing; see *Note Modification Time::.
746 - Function: file-locked-p &optional filename
747 This function returns `nil' if the file FILENAME is not locked by
748 this XEmacs process. It returns `t' if it is locked by this
749 XEmacs, and it returns the name of the user who has locked it if it
750 is locked by someone else.
752 (file-locked-p "foo")
755 - Function: lock-buffer &optional filename
756 This function locks the file FILENAME, if the current buffer is
757 modified. The argument FILENAME defaults to the current buffer's
758 visited file. Nothing is done if the current buffer is not
759 visiting a file, or is not modified.
761 - Function: unlock-buffer
762 This function unlocks the file being visited in the current buffer,
763 if the buffer is modified. If the buffer is not modified, then
764 the file should not be locked, so this function does nothing. It
765 also does nothing if the current buffer is not visiting a file.
767 - Function: ask-user-about-lock filename other-user
768 This function is called when the user tries to modify FILENAME,
769 but it is locked by another user named OTHER-USER. The value it
770 returns determines what happens next:
772 * A value of `t' says to grab the lock on the file. Then this
773 user may edit the file and OTHER-USER loses the lock.
775 * A value of `nil' says to ignore the lock and let this user
776 edit the file anyway.
778 * This function may instead signal a `file-locked' error, in
779 which case the change that the user was about to make does
782 The error message for this error looks like this:
784 error--> File is locked: FILENAME OTHER-USER
786 where FILENAME is the name of the file and OTHER-USER is the
787 name of the user who has locked the file.
789 The default definition of this function asks the user to choose
790 what to do. If you wish, you can replace the `ask-user-about-lock'
791 function with your own version that decides in another way. The
792 code for its usual definition is in `userlock.el'.
795 File: lispref.info, Node: Information about Files, Next: Changing File Attributes, Prev: File Locks, Up: Files
797 Information about Files
798 =======================
800 The functions described in this section all operate on strings that
801 designate file names. All the functions have names that begin with the
802 word `file'. These functions all return information about actual files
803 or directories, so their arguments must all exist as actual files or
804 directories unless otherwise noted.
808 * Testing Accessibility:: Is a given file readable? Writable?
809 * Kinds of Files:: Is it a directory? A symbolic link?
810 * Truenames:: Eliminating symbolic links from a file name.
811 * File Attributes:: How large is it? Any other names? Etc.
814 File: lispref.info, Node: Testing Accessibility, Next: Kinds of Files, Up: Information about Files
816 Testing Accessibility
817 ---------------------
819 These functions test for permission to access a file in specific
822 - Function: file-exists-p filename
823 This function returns `t' if a file named FILENAME appears to
824 exist. This does not mean you can necessarily read the file, only
825 that you can find out its attributes. (On Unix, this is true if
826 the file exists and you have execute permission on the containing
827 directories, regardless of the protection of the file itself.)
829 If the file does not exist, or if fascist access control policies
830 prevent you from finding the attributes of the file, this function
833 - Function: file-readable-p filename
834 This function returns `t' if a file named FILENAME exists and you
835 can read it. It returns `nil' otherwise.
837 (file-readable-p "files.texi")
839 (file-exists-p "/usr/spool/mqueue")
841 (file-readable-p "/usr/spool/mqueue")
844 - Function: file-executable-p filename
845 This function returns `t' if a file named FILENAME exists and you
846 can execute it. It returns `nil' otherwise. If the file is a
847 directory, execute permission means you can check the existence and
848 attributes of files inside the directory, and open those files if
851 - Function: file-writable-p filename
852 This function returns `t' if the file FILENAME can be written or
853 created by you, and `nil' otherwise. A file is writable if the
854 file exists and you can write it. It is creatable if it does not
855 exist, but the specified directory does exist and you can write in
858 In the third example below, `foo' is not writable because the
859 parent directory does not exist, even though the user could create
862 (file-writable-p "~/foo")
864 (file-writable-p "/foo")
866 (file-writable-p "~/no-such-dir/foo")
869 - Function: file-accessible-directory-p dirname
870 This function returns `t' if you have permission to open existing
871 files in the directory whose name as a file is DIRNAME; otherwise
872 (or if there is no such directory), it returns `nil'. The value
873 of DIRNAME may be either a directory name or the file name of a
876 Example: after the following,
878 (file-accessible-directory-p "/foo")
881 we can deduce that any attempt to read a file in `/foo/' will give
884 - Function: file-ownership-preserved-p filename
885 This function returns `t' if deleting the file FILENAME and then
886 creating it anew would keep the file's owner unchanged.
888 - Function: file-newer-than-file-p filename1 filename2
889 This function returns `t' if the file FILENAME1 is newer than file
890 FILENAME2. If FILENAME1 does not exist, it returns `nil'. If
891 FILENAME2 does not exist, it returns `t'.
893 In the following example, assume that the file `aug-19' was written
894 on the 19th, `aug-20' was written on the 20th, and the file
895 `no-file' doesn't exist at all.
897 (file-newer-than-file-p "aug-19" "aug-20")
899 (file-newer-than-file-p "aug-20" "aug-19")
901 (file-newer-than-file-p "aug-19" "no-file")
903 (file-newer-than-file-p "no-file" "aug-19")
906 You can use `file-attributes' to get a file's last modification
907 time as a list of two numbers. *Note File Attributes::.
910 File: lispref.info, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files
912 Distinguishing Kinds of Files
913 -----------------------------
915 This section describes how to distinguish various kinds of files,
916 such as directories, symbolic links, and ordinary files.
918 - Function: file-symlink-p filename
919 If the file FILENAME is a symbolic link, the `file-symlink-p'
920 function returns the file name to which it is linked. This may be
921 the name of a text file, a directory, or even another symbolic
922 link, or it may be a nonexistent file name.
924 If the file FILENAME is not a symbolic link (or there is no such
925 file), `file-symlink-p' returns `nil'.
927 (file-symlink-p "foo")
929 (file-symlink-p "sym-link")
931 (file-symlink-p "sym-link2")
933 (file-symlink-p "/bin")
937 - Function: file-directory-p filename
938 This function returns `t' if FILENAME is the name of an existing
939 directory, `nil' otherwise.
941 (file-directory-p "~rms")
943 (file-directory-p "~rms/lewis/files.texi")
945 (file-directory-p "~rms/lewis/no-such-file")
947 (file-directory-p "$HOME")
950 (substitute-in-file-name "$HOME"))
953 - Function: file-regular-p filename
954 This function returns `t' if the file FILENAME exists and is a
955 regular file (not a directory, symbolic link, named pipe,
956 terminal, or other I/O device).
959 File: lispref.info, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files
964 The "truename" of a file is the name that you get by following
965 symbolic links until none remain, then expanding to get rid of `.' and
966 `..' as components. Strictly speaking, a file need not have a unique
967 truename; the number of distinct truenames a file has is equal to the
968 number of hard links to the file. However, truenames are useful
969 because they eliminate symbolic links as a cause of name variation.
971 - Function: file-truename filename &optional default
972 The function `file-truename' returns the true name of the file
973 FILENAME. This is the name that you get by following symbolic
974 links until none remain.
976 If the filename is relative, DEFAULT is the directory to start
977 with. If DEFAULT is `nil' or missing, the current buffer's value
978 of `default-directory' is used.
980 *Note Buffer File Name::, for related information.
983 File: lispref.info, Node: File Attributes, Prev: Truenames, Up: Information about Files
985 Other Information about Files
986 -----------------------------
988 This section describes the functions for getting detailed information
989 about a file, other than its contents. This information includes the
990 mode bits that control access permission, the owner and group numbers,
991 the number of names, the inode number, the size, and the times of access
994 - Function: file-modes filename
995 This function returns the mode bits of FILENAME, as an integer.
996 The mode bits are also called the file permissions, and they
997 specify access control in the usual Unix fashion. If the
998 low-order bit is 1, then the file is executable by all users, if
999 the second-lowest-order bit is 1, then the file is writable by all
1002 The highest value returnable is 4095 (7777 octal), meaning that
1003 everyone has read, write, and execute permission, that the SUID bit
1004 is set for both others and group, and that the sticky bit is set.
1006 (file-modes "~/junk/diffs")
1007 => 492 ; Decimal integer.
1009 => "754" ; Convert to octal.
1011 (set-file-modes "~/junk/diffs" 438)
1015 => "666" ; Convert to octal.
1018 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
1020 - Function: file-nlinks filename
1021 This functions returns the number of names (i.e., hard links) that
1022 file FILENAME has. If the file does not exist, then this function
1023 returns `nil'. Note that symbolic links have no effect on this
1024 function, because they are not considered to be names of the files
1028 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
1029 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
1033 (file-nlinks "doesnt-exist")
1036 - Function: file-attributes filename
1037 This function returns a list of attributes of file FILENAME. If
1038 the specified file cannot be opened, it returns `nil'.
1040 The elements of the list, in order, are:
1042 0. `t' for a directory, a string for a symbolic link (the name
1043 linked to), or `nil' for a text file.
1045 1. The number of names the file has. Alternate names, also
1046 known as hard links, can be created by using the
1047 `add-name-to-file' function (*note Changing File
1054 4. The time of last access, as a list of two integers. The
1055 first integer has the high-order 16 bits of time, the second
1056 has the low 16 bits. (This is similar to the value of
1057 `current-time'; see *Note Time of Day::.)
1059 5. The time of last modification as a list of two integers (as
1062 6. The time of last status change as a list of two integers (as
1065 7. The size of the file in bytes.
1067 8. The file's modes, as a string of ten letters or dashes, as in
1070 9. `t' if the file's GID would change if file were deleted and
1071 recreated; `nil' otherwise.
1073 10. The file's inode number.
1075 11. The file system number of the file system that the file is
1076 in. This element and the file's inode number together give
1077 enough information to distinguish any two files on the
1078 system--no two files can have the same values for both of
1081 For example, here are the file attributes for `files.texi':
1083 (file-attributes "files.texi")
1097 and here is how the result is interpreted:
1100 is neither a directory nor a symbolic link.
1103 has only one name (the name `files.texi' in the current
1107 is owned by the user with UID 2235.
1110 is in the group with GID 75.
1113 was last accessed on Aug 19 00:09. Use `format-time-string' to
1114 ! convert this number into a time string. *Note Time
1118 was last modified on Aug 19 00:09.
1121 last had its inode changed on Aug 19 00:09.
1124 is 14906 characters long.
1127 has a mode of read and write access for the owner, group, and
1131 would retain the same GID if it were recreated.
1134 has an inode number of 129500.
1137 is on file system number -32252.
projects / chise / xemacs-chise.git- / blob