-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Help Functions, Next: Obsoleteness, Prev: Describing Characters, Up: Documentation
+
+Help Functions
+==============
+
+ XEmacs provides a variety of on-line help functions, all accessible
+to the user as subcommands of the prefix `C-h', or on some keyboards,
+`help'. For more information about them, see *Note Help: (emacs)Help.
+Here we describe some program-level interfaces to the same information.
+
+ - Command: apropos regexp &optional do-all predicate
+ This function finds all symbols whose names contain a match for the
+ regular expression REGEXP, and returns a list of them (*note
+ Regular Expressions::). It also displays the symbols in a buffer
+ named `*Help*', each with a one-line description.
+
+ If DO-ALL is non-`nil', then `apropos' also shows key bindings for
+ the functions that are found.
+
+ If PREDICATE is non-`nil', it should be a function to be called on
+ each symbol that has matched REGEXP. Only symbols for which
+ PREDICATE returns a non-`nil' value are listed or displayed.
+
+ In the first of the following examples, `apropos' finds all the
+ symbols with names containing `exec'. In the second example, it
+ finds and returns only those symbols that are also commands. (We
+ don't show the output that results in the `*Help*' buffer.)
+
+ (apropos "exec")
+ => (Buffer-menu-execute command-execute exec-directory
+ exec-path execute-extended-command execute-kbd-macro
+ executing-kbd-macro executing-macro)
+
+ (apropos "exec" nil 'commandp)
+ => (Buffer-menu-execute execute-extended-command)
+
+ `apropos' is used by various user-level commands, such as `C-h a'
+ (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A'
+ (`command-apropos'), which does an apropos over only those
+ functions which are user commands. `command-apropos' calls
+ `apropos', specifying a PREDICATE to restrict the output to
+ symbols that are commands. The call to `apropos' looks like this:
+
+ (apropos string t 'commandp)
+
+ - Variable: help-map
+ The value of this variable is a local keymap for characters
+ following the Help key, `C-h'.
+
+ - Prefix Command: help-command
+ This symbol is not a function; its function definition is actually
+ the keymap known as `help-map'. It is defined in `help.el' as
+ follows:
+
+ (define-key global-map "\C-h" 'help-command)
+ (fset 'help-command help-map)
+
+ - Function: print-help-return-message &optional function
+ This function builds a string that explains how to restore the
+ previous state of the windows after a help command. After
+ building the message, it applies FUNCTION to it if FUNCTION is
+ non-`nil'. Otherwise it calls `message' to display it in the echo
+ area.
+
+ This function expects to be called inside a
+ `with-output-to-temp-buffer' special form, and expects
+ `standard-output' to have the value bound by that special form.
+ For an example of its use, see the long example in *Note Accessing
+ Documentation::.
+
+ - Variable: help-char
+ The value of this variable is the help character--the character
+ that XEmacs recognizes as meaning Help. By default, it is the
+ character `?\^H' (ASCII 8), which is `C-h'. When XEmacs reads this
+ character, if `help-form' is non-`nil' Lisp expression, it
+ evaluates that expression, and displays the result in a window if
+ it is a string.
+
+ `help-char' can be a character or a key description such as `help'
+ or `(meta h)'.
+
+ Usually the value of `help-form''s value is `nil'. Then the help
+ character has no special meaning at the level of command input, and
+ it becomes part of a key sequence in the normal way. The standard
+ key binding of `C-h' is a prefix key for several general-purpose
+ help features.
+
+ The help character is special after prefix keys, too. If it has no
+ binding as a subcommand of the prefix key, it runs
+ `describe-prefix-bindings', which displays a list of all the
+ subcommands of the prefix key.
+
+ - Variable: help-form
+ If this variable is non-`nil', its value is a form to evaluate
+ whenever the character `help-char' is read. If evaluating the form
+ produces a string, that string is displayed.
+
+ A command that calls `next-command-event' or `next-event' probably
+ should bind `help-form' to a non-`nil' expression while it does
+ input. (The exception is when `C-h' is meaningful input.)
+ Evaluating this expression should result in a string that explains
+ what the input is for and how to enter it properly.
+
+ Entry to the minibuffer binds this variable to the value of
+ `minibuffer-help-form' (*note Minibuffer Misc::).
+
+ - Variable: prefix-help-command
+ This variable holds a function to print help for a prefix
+ character. The function is called when the user types a prefix
+ key followed by the help character, and the help character has no
+ binding after that prefix. The variable's default value is
+ `describe-prefix-bindings'.
+
+ - Command: describe-prefix-bindings
+ This function calls `describe-bindings' to display a list of all
+ the subcommands of the prefix key of the most recent key sequence.
+ The prefix described consists of all but the last event of that
+ key sequence. (The last event is, presumably, the help character.)
+
+ The following two functions are found in the library `helper'. They
+are for modes that want to provide help without relinquishing control,
+such as the "electric" modes. You must load that library with
+`(require 'helper)' in order to use them. Their names begin with
+`Helper' to distinguish them from the ordinary help functions.
+
+ - Command: Helper-describe-bindings
+ This command pops up a window displaying a help buffer containing a
+ listing of all of the key bindings from both the local and global
+ keymaps. It works by calling `describe-bindings'.
+
+ - Command: Helper-help
+ This command provides help for the current mode. It prompts the
+ user in the minibuffer with the message `Help (Type ? for further
+ options)', and then provides assistance in finding out what the key
+ bindings are, and what the mode is intended for. It returns `nil'.
+
+ This can be customized by changing the map `Helper-help-map'.
+
+\1f
+File: lispref.info, Node: Obsoleteness, Prev: Help Functions, Up: Documentation
+
+Obsoleteness
+============
+
+ As you add functionality to a package, you may at times want to
+replace an older function with a new one. To preserve compatibility
+with existing code, the older function needs to still exist; but users
+of that function should be told to use the newer one instead. XEmacs
+Lisp lets you mark a function or variable as "obsolete", and indicate
+what should be used instead.
+
+ - Command: make-obsolete function new
+ This function indicates that FUNCTION is an obsolete function, and
+ the function NEW should be used instead. The byte compiler will
+ issue a warning to this effect when it encounters a usage of the
+ older function, and the help system will also note this in the
+ function's documentation. NEW can also be a string (if there is
+ not a single function with the same functionality any more), and
+ should be a descriptive statement, such as "use FOO or BAR
+ instead" or "this function is unnecessary".
+
+ - Command: make-obsolete-variable variable new
+ This is like `make-obsolete' but is for variables instead of
+ functions.
+
+ - Function: define-obsolete-function-alias oldfun newfun
+ This function combines `make-obsolete' and `define-function',
+ declaring OLDFUN to be an obsolete variant of NEWFUN and defining
+ OLDFUN as an alias for NEWFUN.
+
+ - Function: define-obsolete-variable-alias oldvar newvar
+ This is like `define-obsolete-function-alias' but for variables.
+
+ Note that you should not normally put obsoleteness information
+explicitly in a function or variable's doc string. The obsoleteness
+information that you specify using the above functions will be displayed
+whenever the doc string is displayed, and by adding it explicitly the
+result is redundancy.
+
+ Also, if an obsolete function is substantially the same as a newer
+one but is not actually an alias, you should consider omitting the doc
+string entirely (use a null string `""' as the doc string). That way,
+the user is told about the obsoleteness and is forced to look at the
+documentation of the new function, making it more likely that he will
+use the new function.
+
+ - Function: function-obsoleteness-doc function
+ If FUNCTION is obsolete, this function returns a string describing
+ this. This is the message that is printed out during byte
+ compilation or in the function's documentation. If FUNCTION is
+ not obsolete, `nil' is returned.
+
+ - Function: variable-obsoleteness-doc variable
+ This is like `function-obsoleteness-doc' but for variables.
+
+ The obsoleteness information is stored internally by putting a
+property `byte-obsolete-info' (for functions) or
+`byte-obsolete-variable' (for variables) on the symbol that specifies
+the obsolete function or variable. For more information, see the
+implementation of `make-obsolete' and `make-obsolete-variable' in
+`lisp/bytecomp/bytecomp-runtime.el'.
+
+\1f
+File: lispref.info, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top
+
+Files
+*****
+
+ In XEmacs, you can find, create, view, save, and otherwise work with
+files and file directories. This chapter describes most of the
+file-related functions of XEmacs Lisp, but a few others are described in
+*Note Buffers::, and those related to backups and auto-saving are
+described in *Note Backups and Auto-Saving::.
+
+ Many of the file functions take one or more arguments that are file
+names. A file name is actually a string. Most of these functions
+expand file name arguments using `expand-file-name', so that `~' is
+handled correctly, as are relative file names (including `../'). These
+functions don't recognize environment variable substitutions such as
+`$HOME'. *Note File Name Expansion::.
+
+* Menu:
+
+* Visiting Files:: Reading files into Emacs buffers for editing.
+* Saving Buffers:: Writing changed buffers back into files.
+* Reading from Files:: Reading files into buffers without visiting.
+* Writing to Files:: Writing new files from parts of buffers.
+* File Locks:: Locking and unlocking files, to prevent
+ simultaneous editing by two people.
+* Information about Files:: Testing existence, accessibility, size of files.
+* Changing File Attributes:: Renaming files, changing protection, etc.
+* File Names:: Decomposing and expanding file names.
+* Contents of Directories:: Getting a list of the files in a directory.
+* Create/Delete Dirs:: Creating and Deleting Directories.
+* Magic File Names:: Defining "magic" special handling
+ for certain file names.
+* Partial Files:: Treating a section of a buffer as a file.
+* Format Conversion:: Conversion to and from various file formats.
+* Files and MS-DOS:: Distinguishing text and binary files on MS-DOS.
+
+\1f
+File: lispref.info, Node: Visiting Files, Next: Saving Buffers, Up: Files
+
+Visiting Files
+==============
+
+ Visiting a file means reading a file into a buffer. Once this is
+done, we say that the buffer is "visiting" that file, and call the file
+"the visited file" of the buffer.
+
+ A file and a buffer are two different things. A file is information
+recorded permanently in the computer (unless you delete it). A buffer,
+on the other hand, is information inside of XEmacs that will vanish at
+the end of the editing session (or when you kill the buffer). Usually,
+a buffer contains information that you have copied from a file; then we
+say the buffer is visiting that file. The copy in the buffer is what
+you modify with editing commands. Such changes to the buffer do not
+change the file; therefore, to make the changes permanent, you must
+"save" the buffer, which means copying the altered buffer contents back
+into the file.
+
+ In spite of the distinction between files and buffers, people often
+refer to a file when they mean a buffer and vice-versa. Indeed, we say,
+"I am editing a file," rather than, "I am editing a buffer that I will
+soon save as a file of the same name." Humans do not usually need to
+make the distinction explicit. When dealing with a computer program,
+however, it is good to keep the distinction in mind.
+
+* Menu:
+
+* Visiting Functions:: The usual interface functions for visiting.
+* Subroutines of Visiting:: Lower-level subroutines that they use.
+
+\1f
+File: lispref.info, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files
+
+Functions for Visiting Files
+----------------------------
+
+ This section describes the functions normally used to visit files.
+For historical reasons, these functions have names starting with
+`find-' rather than `visit-'. *Note Buffer File Name::, for functions
+and variables that access the visited file name of a buffer or that
+find an existing buffer by its visited file name.
+
+ In a Lisp program, if you want to look at the contents of a file but
+not alter it, the fastest way is to use `insert-file-contents' in a
+temporary buffer. Visiting the file is not necessary and takes longer.
+*Note Reading from Files::.
+
+ - Command: find-file filename
+ This command selects a buffer visiting the file FILENAME, using an
+ existing buffer if there is one, and otherwise creating a new
+ buffer and reading the file into it. It also returns that buffer.
+
+ The body of the `find-file' function is very simple and looks like
+ this:
+
+ (switch-to-buffer (find-file-noselect filename))
+
+ (See `switch-to-buffer' in *Note Displaying Buffers::.)
+
+ When `find-file' is called interactively, it prompts for FILENAME
+ in the minibuffer.
+
+ - Function: find-file-noselect filename &optional nowarn
+ This function is the guts of all the file-visiting functions. It
+ finds or creates a buffer visiting the file FILENAME, and returns
+ it. It uses an existing buffer if there is one, and otherwise
+ creates a new buffer and reads the file into it. You may make the
+ buffer current or display it in a window if you wish, but this
+ function does not do so.
+
+ When `find-file-noselect' uses an existing buffer, it first
+ verifies that the file has not changed since it was last visited or
+ saved in that buffer. If the file has changed, then this function
+ asks the user whether to reread the changed file. If the user says
+ `yes', any changes previously made in the buffer are lost.
+
+ If `find-file-noselect' needs to create a buffer, and there is no
+ file named FILENAME, it displays the message `New file' in the
+ echo area, and leaves the buffer empty.
+
+ If NOWARN is non-`nil', various warnings that XEmacs normally
+ gives (e.g. if another buffer is already visiting FILENAME but
+ FILENAME has been removed from disk since that buffer was created)
+ are suppressed.
+
+ The `find-file-noselect' function calls `after-find-file' after
+ reading the file (*note Subroutines of Visiting::). That function
+ sets the buffer major mode, parses local variables, warns the user
+ if there exists an auto-save file more recent than the file just
+ visited, and finishes by running the functions in
+ `find-file-hooks'.
+
+ The `find-file-noselect' function returns the buffer that is
+ visiting the file FILENAME.
+
+ (find-file-noselect "/etc/fstab")
+ => #<buffer fstab>
+
+ - Command: find-file-other-window filename
+ This command selects a buffer visiting the file FILENAME, but does
+ so in a window other than the selected window. It may use another
+ existing window or split a window; see *Note Displaying Buffers::.
+
+ When this command is called interactively, it prompts for FILENAME.
+
+ - Command: find-file-read-only filename
+ This command selects a buffer visiting the file FILENAME, like
+ `find-file', but it marks the buffer as read-only. *Note Read
+ Only Buffers::, for related functions and variables.
+
+ When this command is called interactively, it prompts for FILENAME.
+
+ - Command: view-file filename &optional other-window-p
+ This command visits FILENAME in View mode, and displays it in a
+ recursive edit, returning to the previous buffer when done. View
+ mode is a mode that allows you to skim rapidly through the file
+ but does not let you modify it. Entering View mode runs the
+ normal hook `view-mode-hook'. *Note Hooks::.
+
+ When `view-file' is called interactively, it prompts for FILENAME.
+
+ With non-`nil' prefix arg OTHER-WINDOW-P, visit FILENAME in
+ another window.
+
+ - Variable: find-file-hooks
+ The value of this variable is a list of functions to be called
+ after a file is visited. The file's local-variables specification
+ (if any) will have been processed before the hooks are run. The
+ buffer visiting the file is current when the hook functions are
+ run.
+
+ This variable works just like a normal hook, but we think that
+ renaming it would not be advisable.
+
+ - Variable: find-file-not-found-hooks
+ The value of this variable is a list of functions to be called when
+ `find-file' or `find-file-noselect' is passed a nonexistent file
+ name. `find-file-noselect' calls these functions as soon as it
+ detects a nonexistent file. It calls them in the order of the
+ list, until one of them returns non-`nil'. `buffer-file-name' is
+ already set up.
+
+ This is not a normal hook because the values of the functions are
+ used and they may not all be called.
+
+\1f
+File: lispref.info, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files
+
+Subroutines of Visiting
+-----------------------
+
+ The `find-file-noselect' function uses the `create-file-buffer' and
+`after-find-file' functions as subroutines. Sometimes it is useful to
+call them directly.
+
+ - Function: create-file-buffer filename
+ This function creates a suitably named buffer for visiting
+ FILENAME, and returns it. It uses FILENAME (sans directory) as
+ the name if that name is free; otherwise, it appends a string such
+ as `<2>' to get an unused name. See also *Note Creating Buffers::.
+
+ *Please note:* `create-file-buffer' does _not_ associate the new
+ buffer with a file and does not select the buffer. It also does
+ not use the default major mode.
+
+ (create-file-buffer "foo")
+ => #<buffer foo>
+ (create-file-buffer "foo")
+ => #<buffer foo<2>>
+ (create-file-buffer "foo")
+ => #<buffer foo<3>>
+
+ This function is used by `find-file-noselect'. It uses
+ `generate-new-buffer' (*note Creating Buffers::).
+
+ - Function: after-find-file &optional error warn noauto
+ This function sets the buffer major mode, and parses local
+ variables (*note Auto Major Mode::). It is called by
+ `find-file-noselect' and by the default revert function (*note
+ Reverting::).
+
+ If reading the file got an error because the file does not exist,
+ but its directory does exist, the caller should pass a non-`nil'
+ value for ERROR. In that case, `after-find-file' issues a warning:
+ `(New File)'. For more serious errors, the caller should usually
+ not call `after-find-file'.
+
+ If WARN is non-`nil', then this function issues a warning if an
+ auto-save file exists and is more recent than the visited file.
+
+ If NOAUTO is non-`nil', then this function does not turn on
+ auto-save mode; otherwise, it does.
+
+ The last thing `after-find-file' does is call all the functions in
+ `find-file-hooks'.
+
+\1f
+File: lispref.info, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files
+
+Saving Buffers
+==============
+
+ When you edit a file in XEmacs, you are actually working on a buffer
+that is visiting that file--that is, the contents of the file are
+copied into the buffer and the copy is what you edit. Changes to the
+buffer do not change the file until you "save" the buffer, which means
+copying the contents of the buffer into the file.
+
+ - Command: save-buffer &optional backup-option
+ This function saves the contents of the current buffer in its
+ visited file if the buffer has been modified since it was last
+ visited or saved. Otherwise it does nothing.
+
+ `save-buffer' is responsible for making backup files. Normally,
+ BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only
+ if this is the first save since visiting the file. Other values
+ for BACKUP-OPTION request the making of backup files in other
+ circumstances:
+
+ * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the
+ `save-buffer' function marks this version of the file to be
+ backed up when the buffer is next saved.
+
+ * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the
+ `save-buffer' function unconditionally backs up the previous
+ version of the file before saving it.
+
+ - Command: save-some-buffers &optional save-silently-p exiting
+ This command saves some modified file-visiting buffers. Normally
+ it asks the user about each buffer. But if SAVE-SILENTLY-P is
+ non-`nil', it saves all the file-visiting buffers without querying
+ the user.
+
+ The optional EXITING argument, if non-`nil', requests this
+ function to offer also to save certain other buffers that are not
+ visiting files. These are buffers that have a non-`nil' local
+ value of `buffer-offer-save'. (A user who says yes to saving one
+ of these is asked to specify a file name to use.) The
+ `save-buffers-kill-emacs' function passes a non-`nil' value for
+ this argument.
+
+ - Variable: buffer-offer-save
+ When this variable is non-`nil' in a buffer, XEmacs offers to save
+ the buffer on exit even if the buffer is not visiting a file. The
+ variable is automatically local in all buffers. Normally, Mail
+ mode (used for editing outgoing mail) sets this to `t'.
+
+ - Command: write-file filename
+ This function writes the current buffer into file FILENAME, makes
+ the buffer visit that file, and marks it not modified. Then it
+ renames the buffer based on FILENAME, appending a string like `<2>'
+ if necessary to make a unique buffer name. It does most of this
+ work by calling `set-visited-file-name' and `save-buffer'.
+
+ - Variable: write-file-hooks
+ The value of this variable is a list of functions to be called
+ before writing out a buffer to its visited file. If one of them
+ returns non-`nil', the file is considered already written and the
+ rest of the functions are not called, nor is the usual code for
+ writing the file executed.
+
+ If a function in `write-file-hooks' returns non-`nil', it is
+ responsible for making a backup file (if that is appropriate). To
+ do so, execute the following code:
+
+ (or buffer-backed-up (backup-buffer))
+
+ You might wish to save the file modes value returned by
+ `backup-buffer' and use that to set the mode bits of the file that
+ you write. This is what `save-buffer' normally does.
+
+ Even though this is not a normal hook, you can use `add-hook' and
+ `remove-hook' to manipulate the list. *Note Hooks::.
+
+ - Variable: local-write-file-hooks
+ This works just like `write-file-hooks', but it is intended to be
+ made local to particular buffers. It's not a good idea to make
+ `write-file-hooks' local to a buffer--use this variable instead.
+
+ The variable is marked as a permanent local, so that changing the
+ major mode does not alter a buffer-local value. This is
+ convenient for packages that read "file" contents in special ways,
+ and set up hooks to save the data in a corresponding way.
+
+ - Variable: write-contents-hooks
+ This works just like `write-file-hooks', but it is intended for
+ hooks that pertain to the contents of the file, as opposed to
+ hooks that pertain to where the file came from. Such hooks are
+ usually set up by major modes, as buffer-local bindings for this
+ variable. Switching to a new major mode always resets this
+ variable.
+
+ - Variable: after-save-hook
+ This normal hook runs after a buffer has been saved in its visited
+ file.
+
+ - Variable: file-precious-flag
+ If this variable is non-`nil', then `save-buffer' protects against
+ I/O errors while saving by writing the new file to a temporary
+ name instead of the name it is supposed to have, and then renaming
+ it to the intended name after it is clear there are no errors.
+ This procedure prevents problems such as a lack of disk space from
+ resulting in an invalid file.
+
+ As a side effect, backups are necessarily made by copying. *Note
+ Rename or Copy::. Yet, at the same time, saving a precious file
+ always breaks all hard links between the file you save and other
+ file names.
+
+ Some modes set this variable non-`nil' locally in particular
+ buffers.
+
+ - User Option: require-final-newline
+ This variable determines whether files may be written out that do
+ _not_ end with a newline. If the value of the variable is `t',
+ then `save-buffer' silently adds a newline at the end of the file
+ whenever the buffer being saved does not already end in one. If
+ the value of the variable is non-`nil', but not `t', then
+ `save-buffer' asks the user whether to add a newline each time the
+ case arises.
+
+ If the value of the variable is `nil', then `save-buffer' doesn't
+ add newlines at all. `nil' is the default value, but a few major
+ modes set it to `t' in particular buffers.
+
+\1f
+File: lispref.info, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files
+
+Reading from Files
+==================
+
+ You can copy a file from the disk and insert it into a buffer using
+the `insert-file-contents' function. Don't use the user-level command
+`insert-file' in a Lisp program, as that sets the mark.
+
+ - Function: insert-file-contents filename &optional visit start end
+ replace
+ This function inserts the contents of file FILENAME into the
+ current buffer after point. It returns a list of the absolute
+ file name and the length of the data inserted. An error is
+ signaled if FILENAME is not the name of a file that can be read.
+
+ The function `insert-file-contents' checks the file contents
+ against the defined file formats, and converts the file contents if
+ appropriate. *Note Format Conversion::. It also calls the
+ functions in the list `after-insert-file-functions'; see *Note
+ Saving Properties::.
+
+ If VISIT is non-`nil', this function additionally marks the buffer
+ as unmodified and sets up various fields in the buffer so that it
+ is visiting the file FILENAME: these include the buffer's visited
+ file name and its last save file modtime. This feature is used by
+ `find-file-noselect' and you probably should not use it yourself.
+
+ If START and END are non-`nil', they should be integers specifying
+ the portion of the file to insert. In this case, VISIT must be
+ `nil'. For example,
+
+ (insert-file-contents filename nil 0 500)
+
+ inserts the first 500 characters of a file.
+
+ If the argument REPLACE is non-`nil', it means to replace the
+ contents of the buffer (actually, just the accessible portion)
+ with the contents of the file. This is better than simply
+ deleting the buffer contents and inserting the whole file, because
+ (1) it preserves some marker positions and (2) it puts less data
+ in the undo list.
+
+ If you want to pass a file name to another process so that another
+program can read the file, use the function `file-local-copy'; see
+*Note Magic File Names::.
+
+\1f
+File: lispref.info, Node: Writing to Files, Next: File Locks, Prev: Reading from Files, Up: Files
+
+Writing to Files
+================
+
+ You can write the contents of a buffer, or part of a buffer, directly
+to a file on disk using the `append-to-file' and `write-region'
+functions. Don't use these functions to write to files that are being
+visited; that could cause confusion in the mechanisms for visiting.
+
+ - Command: append-to-file start end filename
+ This function appends the contents of the region delimited by
+ START and END in the current buffer to the end of file FILENAME.
+ If that file does not exist, it is created. If that file exists
+ it is overwritten. This function returns `nil'.
+
+ An error is signaled if FILENAME specifies a nonwritable file, or
+ a nonexistent file in a directory where files cannot be created.
+
+ - Command: write-region start end filename &optional append visit
+ This function writes the region delimited by START and END in the
+ current buffer into the file specified by FILENAME.
+
+ If START is a string, then `write-region' writes or appends that
+ string, rather than text from the buffer.
+
+ If APPEND is non-`nil', then the specified text is appended to the
+ existing file contents (if any).
+
+ If VISIT is `t', then XEmacs establishes an association between
+ the buffer and the file: the buffer is then visiting that file.
+ It also sets the last file modification time for the current
+ buffer to FILENAME's modtime, and marks the buffer as not
+ modified. This feature is used by `save-buffer', but you probably
+ should not use it yourself.
+
+ If VISIT is a string, it specifies the file name to visit. This
+ way, you can write the data to one file (FILENAME) while recording
+ the buffer as visiting another file (VISIT). The argument VISIT
+ is used in the echo area message and also for file locking; VISIT
+ is stored in `buffer-file-name'. This feature is used to
+ implement `file-precious-flag'; don't use it yourself unless you
+ really know what you're doing.
+
+ The function `write-region' converts the data which it writes to
+ the appropriate file formats specified by `buffer-file-format'.
+ *Note Format Conversion::. It also calls the functions in the list
+ `write-region-annotate-functions'; see *Note Saving Properties::.
+
+ Normally, `write-region' displays a message `Wrote file FILENAME'
+ in the echo area. If VISIT is neither `t' nor `nil' nor a string,
+ then this message is inhibited. This feature is useful for
+ programs that use files for internal purposes, files that the user
+ does not need to know about.
+
+\1f
+File: lispref.info, Node: File Locks, Next: Information about Files, Prev: Writing to Files, Up: Files
+
+File Locks
+==========
+
+ When two users edit the same file at the same time, they are likely
+to interfere with each other. XEmacs tries to prevent this situation
+from arising by recording a "file lock" when a file is being modified.
+XEmacs can then detect the first attempt to modify a buffer visiting a
+file that is locked by another XEmacs process, and ask the user what to
+do.
+
+ File locks do not work properly when multiple machines can share
+file systems, such as with NFS. Perhaps a better file locking system
+will be implemented in the future. When file locks do not work, it is
+possible for two users to make changes simultaneously, but XEmacs can
+still warn the user who saves second. Also, the detection of
+modification of a buffer visiting a file changed on disk catches some
+cases of simultaneous editing; see *Note Modification Time::.
+
+ - Function: file-locked-p &optional filename
+ This function returns `nil' if the file FILENAME is not locked by
+ this XEmacs process. It returns `t' if it is locked by this
+ XEmacs, and it returns the name of the user who has locked it if it
+ is locked by someone else.
+
+ (file-locked-p "foo")
+ => nil
+
+ - Function: lock-buffer &optional filename
+ This function locks the file FILENAME, if the current buffer is
+ modified. The argument FILENAME defaults to the current buffer's
+ visited file. Nothing is done if the current buffer is not
+ visiting a file, or is not modified.
+
+ - Function: unlock-buffer
+ This function unlocks the file being visited in the current buffer,
+ if the buffer is modified. If the buffer is not modified, then
+ the file should not be locked, so this function does nothing. It
+ also does nothing if the current buffer is not visiting a file.
+
+ - Function: ask-user-about-lock filename other-user
+ This function is called when the user tries to modify FILENAME,
+ but it is locked by another user named OTHER-USER. The value it
+ returns determines what happens next:
+
+ * A value of `t' says to grab the lock on the file. Then this
+ user may edit the file and OTHER-USER loses the lock.
+
+ * A value of `nil' says to ignore the lock and let this user
+ edit the file anyway.
+
+ * This function may instead signal a `file-locked' error, in
+ which case the change that the user was about to make does
+ not take place.
+
+ The error message for this error looks like this:
+
+ error--> File is locked: FILENAME OTHER-USER
+
+ where FILENAME is the name of the file and OTHER-USER is the
+ name of the user who has locked the file.
+
+ The default definition of this function asks the user to choose
+ what to do. If you wish, you can replace the `ask-user-about-lock'
+ function with your own version that decides in another way. The
+ code for its usual definition is in `userlock.el'.
+
+\1f
+File: lispref.info, Node: Information about Files, Next: Changing File Attributes, Prev: File Locks, Up: Files
+
+Information about Files
+=======================
+
+ The functions described in this section all operate on strings that
+designate file names. All the functions have names that begin with the
+word `file'. These functions all return information about actual files
+or directories, so their arguments must all exist as actual files or
+directories unless otherwise noted.
+
+* Menu:
+
+* Testing Accessibility:: Is a given file readable? Writable?
+* Kinds of Files:: Is it a directory? A symbolic link?
+* Truenames:: Eliminating symbolic links from a file name.
+* File Attributes:: How large is it? Any other names? Etc.
+
+\1f
+File: lispref.info, Node: Testing Accessibility, Next: Kinds of Files, Up: Information about Files
+
+Testing Accessibility
+---------------------
+
+ These functions test for permission to access a file in specific
+ways.
+
+ - Function: file-exists-p filename
+ This function returns `t' if a file named FILENAME appears to
+ exist. This does not mean you can necessarily read the file, only
+ that you can find out its attributes. (On Unix, this is true if
+ the file exists and you have execute permission on the containing
+ directories, regardless of the protection of the file itself.)
+
+ If the file does not exist, or if fascist access control policies
+ prevent you from finding the attributes of the file, this function
+ returns `nil'.
+
+ - Function: file-readable-p filename
+ This function returns `t' if a file named FILENAME exists and you
+ can read it. It returns `nil' otherwise.
+
+ (file-readable-p "files.texi")
+ => t
+ (file-exists-p "/usr/spool/mqueue")
+ => t
+ (file-readable-p "/usr/spool/mqueue")
+ => nil
+
+ - Function: file-executable-p filename
+ This function returns `t' if a file named FILENAME exists and you
+ can execute it. It returns `nil' otherwise. If the file is a
+ directory, execute permission means you can check the existence and
+ attributes of files inside the directory, and open those files if
+ their modes permit.
+
+ - Function: file-writable-p filename
+ This function returns `t' if the file FILENAME can be written or
+ created by you, and `nil' otherwise. A file is writable if the
+ file exists and you can write it. It is creatable if it does not
+ exist, but the specified directory does exist and you can write in
+ that directory.
+
+ In the third example below, `foo' is not writable because the
+ parent directory does not exist, even though the user could create
+ such a directory.
+
+ (file-writable-p "~/foo")
+ => t
+ (file-writable-p "/foo")
+ => nil
+ (file-writable-p "~/no-such-dir/foo")
+ => nil
+
+ - Function: file-accessible-directory-p dirname
+ This function returns `t' if you have permission to open existing
+ files in the directory whose name as a file is DIRNAME; otherwise
+ (or if there is no such directory), it returns `nil'. The value
+ of DIRNAME may be either a directory name or the file name of a
+ directory.
+
+ Example: after the following,
+
+ (file-accessible-directory-p "/foo")
+ => nil
+
+ we can deduce that any attempt to read a file in `/foo/' will give
+ an error.
+
+ - Function: file-ownership-preserved-p filename
+ This function returns `t' if deleting the file FILENAME and then
+ creating it anew would keep the file's owner unchanged.
+
+ - Function: file-newer-than-file-p filename1 filename2
+ This function returns `t' if the file FILENAME1 is newer than file
+ FILENAME2. If FILENAME1 does not exist, it returns `nil'. If
+ FILENAME2 does not exist, it returns `t'.
+
+ In the following example, assume that the file `aug-19' was written
+ on the 19th, `aug-20' was written on the 20th, and the file
+ `no-file' doesn't exist at all.
+
+ (file-newer-than-file-p "aug-19" "aug-20")
+ => nil
+ (file-newer-than-file-p "aug-20" "aug-19")
+ => t
+ (file-newer-than-file-p "aug-19" "no-file")
+ => t
+ (file-newer-than-file-p "no-file" "aug-19")
+ => nil
+
+ You can use `file-attributes' to get a file's last modification
+ time as a list of two numbers. *Note File Attributes::.
+
+\1f
+File: lispref.info, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files
+
+Distinguishing Kinds of Files
+-----------------------------
+
+ This section describes how to distinguish various kinds of files,
+such as directories, symbolic links, and ordinary files.
+
+ - Function: file-symlink-p filename
+ If the file FILENAME is a symbolic link, the `file-symlink-p'
+ function returns the file name to which it is linked. This may be
+ the name of a text file, a directory, or even another symbolic
+ link, or it may be a nonexistent file name.
+
+ If the file FILENAME is not a symbolic link (or there is no such
+ file), `file-symlink-p' returns `nil'.
+
+ (file-symlink-p "foo")
+ => nil
+ (file-symlink-p "sym-link")
+ => "foo"
+ (file-symlink-p "sym-link2")
+ => "sym-link"
+ (file-symlink-p "/bin")
+ => "/pub/bin"
+
+
+ - Function: file-directory-p filename
+ This function returns `t' if FILENAME is the name of an existing
+ directory, `nil' otherwise.
+
+ (file-directory-p "~rms")
+ => t
+ (file-directory-p "~rms/lewis/files.texi")
+ => nil
+ (file-directory-p "~rms/lewis/no-such-file")
+ => nil
+ (file-directory-p "$HOME")
+ => nil
+ (file-directory-p
+ (substitute-in-file-name "$HOME"))
+ => t
+
+ - Function: file-regular-p filename
+ This function returns `t' if the file FILENAME exists and is a
+ regular file (not a directory, symbolic link, named pipe,
+ terminal, or other I/O device).
+
+\1f
+File: lispref.info, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files
+
+Truenames
+---------
+
+ The "truename" of a file is the name that you get by following
+symbolic links until none remain, then expanding to get rid of `.' and
+`..' as components. Strictly speaking, a file need not have a unique
+truename; the number of distinct truenames a file has is equal to the
+number of hard links to the file. However, truenames are useful
+because they eliminate symbolic links as a cause of name variation.
+
+ - Function: file-truename filename &optional default
+ The function `file-truename' returns the true name of the file
+ FILENAME. This is the name that you get by following symbolic
+ links until none remain.
+
+ If the filename is relative, DEFAULT is the directory to start
+ with. If DEFAULT is `nil' or missing, the current buffer's value
+ of `default-directory' is used.
+
+ *Note Buffer File Name::, for related information.
+
+\1f
File: lispref.info, Node: File Attributes, Prev: Truenames, Up: Information about Files
Other Information about Files
`-32252'
is on file system number -32252.
-\1f
-File: lispref.info, Node: Changing File Attributes, Next: File Names, Prev: Information about Files, Up: Files
-
-Changing File Names and Attributes
-==================================
-
- The functions in this section rename, copy, delete, link, and set the
-modes of files.
-
- In the functions that have an argument NEWNAME, if a file by the
-name of NEWNAME already exists, the actions taken depend on the value
-of the argument OK-IF-ALREADY-EXISTS:
-
- * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is
- `nil'.
-
- * Request confirmation if OK-IF-ALREADY-EXISTS is a number.
-
- * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
- is any other value.
-
- - Command: add-name-to-file oldname newname &optional
- ok-if-already-exists
- This function gives the file named OLDNAME the additional name
- NEWNAME. This means that NEWNAME becomes a new "hard link" to
- OLDNAME.
-
- In the first part of the following example, we list two files,
- `foo' and `foo3'.
-
- % ls -l fo*
- -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
- -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
-
- Then we evaluate the form `(add-name-to-file "~/lewis/foo"
- "~/lewis/foo2")'. Again we list the files. This shows two names,
- `foo' and `foo2'.
-
- (add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
- => nil
-
- % ls -l fo*
- -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
- -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
- -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
-
- Finally, we evaluate the following:
-
- (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
-
- and list the files again. Now there are three names for one file:
- `foo', `foo2', and `foo3'. The old contents of `foo3' are lost.
-
- (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
- => nil
-
- % ls -l fo*
- -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
- -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
- -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
-
- This function is meaningless on VMS, where multiple names for one
- file are not allowed.
-
- See also `file-nlinks' in *Note File Attributes::.
-
- - Command: rename-file filename newname &optional ok-if-already-exists
- This command renames the file FILENAME as NEWNAME.
-
- If FILENAME has additional names aside from FILENAME, it continues
- to have those names. In fact, adding the name NEWNAME with
- `add-name-to-file' and then deleting FILENAME has the same effect
- as renaming, aside from momentary intermediate states.
-
- In an interactive call, this function prompts for FILENAME and
- NEWNAME in the minibuffer; also, it requests confirmation if
- NEWNAME already exists.
-
- - Command: copy-file oldname newname &optional ok-if-exists time
- This command copies the file OLDNAME to NEWNAME. An error is
- signaled if OLDNAME does not exist.
-
- If TIME is non-`nil', then this functions gives the new file the
- same last-modified time that the old one has. (This works on only
- some operating systems.)
-
- In an interactive call, this function prompts for FILENAME and
- NEWNAME in the minibuffer; also, it requests confirmation if
- NEWNAME already exists.
-
- - Command: delete-file filename
- This command deletes the file FILENAME, like the shell command `rm
- FILENAME'. If the file has multiple names, it continues to exist
- under the other names.
-
- A suitable kind of `file-error' error is signaled if the file does
- not exist, or is not deletable. (On Unix, a file is deletable if
- its directory is writable.)
-
- See also `delete-directory' in *Note Create/Delete Dirs::.
-
- - Command: make-symbolic-link filename newname &optional ok-if-exists
- This command makes a symbolic link to FILENAME, named NEWNAME.
- This is like the shell command `ln -s FILENAME NEWNAME'.
-
- In an interactive call, this function prompts for FILENAME and
- NEWNAME in the minibuffer; also, it requests confirmation if
- NEWNAME already exists.
-
- - Function: define-logical-name varname string
- This function defines the logical name NAME to have the value
- STRING. It is available only on VMS.
-
- - Function: set-file-modes filename mode
- This function sets mode bits of FILENAME to MODE (which must be an
- integer). Only the low 12 bits of MODE are used.
-
- - Function: set-default-file-modes mode
- This function sets the default file protection for new files
- created by XEmacs and its subprocesses. Every file created with
- XEmacs initially has this protection. On Unix, the default
- protection is the bitwise complement of the "umask" value.
-
- The argument MODE must be an integer. Only the low 9 bits of MODE
- are used.
-
- Saving a modified version of an existing file does not count as
- creating the file; it does not change the file's mode, and does
- not use the default file protection.
-
- - Function: default-file-modes
- This function returns the current default protection value.
-
- On MS-DOS, there is no such thing as an "executable" file mode bit.
-So Emacs considers a file executable if its name ends in `.com', `.bat'
-or `.exe'. This is reflected in the values returned by `file-modes'
-and `file-attributes'.
-
-\1f
-File: lispref.info, Node: File Names, Next: Contents of Directories, Prev: Changing File Attributes, Up: Files
-
-File Names
-==========
-
- Files are generally referred to by their names, in XEmacs as
-elsewhere. File names in XEmacs are represented as strings. The
-functions that operate on a file all expect a file name argument.
-
- In addition to operating on files themselves, XEmacs Lisp programs
-often need to operate on the names; i.e., to take them apart and to use
-part of a name to construct related file names. This section describes
-how to manipulate file names.
-
- The functions in this section do not actually access files, so they
-can operate on file names that do not refer to an existing file or
-directory.
-
- On VMS, all these functions understand both VMS file-name syntax and
-Unix syntax. This is so that all the standard Lisp libraries can
-specify file names in Unix syntax and work properly on VMS without
-change. On MS-DOS, these functions understand MS-DOS file-name syntax
-as well as Unix syntax.
-
-* Menu:
-
-* File Name Components:: The directory part of a file name, and the rest.
-* Directory Names:: A directory's name as a directory
- is different from its name as a file.
-* Relative File Names:: Some file names are relative to a current directory.
-* File Name Expansion:: Converting relative file names to absolute ones.
-* Unique File Names:: Generating names for temporary files.
-* File Name Completion:: Finding the completions for a given file name.
-* User Name Completion:: Finding the completions for a given user name.
-
-\1f
-File: lispref.info, Node: File Name Components, Next: Directory Names, Up: File Names
-
-File Name Components
---------------------
-
- The operating system groups files into directories. To specify a
-file, you must specify the directory and the file's name within that
-directory. Therefore, XEmacs considers a file name as having two main
-parts: the "directory name" part, and the "nondirectory" part (or "file
-name within the directory"). Either part may be empty. Concatenating
-these two parts reproduces the original file name.
-
- On Unix, the directory part is everything up to and including the
-last slash; the nondirectory part is the rest. The rules in VMS syntax
-are complicated.
-
- For some purposes, the nondirectory part is further subdivided into
-the name proper and the "version number". On Unix, only backup files
-have version numbers in their names; on VMS, every file has a version
-number, but most of the time the file name actually used in XEmacs
-omits the version number. Version numbers are found mostly in
-directory lists.
-
- - Function: file-name-directory filename
- This function returns the directory part of FILENAME (or `nil' if
- FILENAME does not include a directory part). On Unix, the
- function returns a string ending in a slash. On VMS, it returns a
- string ending in one of the three characters `:', `]', or `>'.
-
- (file-name-directory "lewis/foo") ; Unix example
- => "lewis/"
- (file-name-directory "foo") ; Unix example
- => nil
- (file-name-directory "[X]FOO.TMP") ; VMS example
- => "[X]"
-
- - Function: file-name-nondirectory filename
- This function returns the nondirectory part of FILENAME.
-
- (file-name-nondirectory "lewis/foo")
- => "foo"
- (file-name-nondirectory "foo")
- => "foo"
- ;; The following example is accurate only on VMS.
- (file-name-nondirectory "[X]FOO.TMP")
- => "FOO.TMP"
-
- - Function: file-name-sans-versions filename &optional
- keep-backup-version
- This function returns FILENAME without any file version numbers,
- backup version numbers, or trailing tildes.
-
- If KEEP-BACKUP-VERSION is non-`nil', we do not remove backup
- version numbers, only true file version numbers.
-
- (file-name-sans-versions "~rms/foo.~1~")
- => "~rms/foo"
- (file-name-sans-versions "~rms/foo~")
- => "~rms/foo"
- (file-name-sans-versions "~rms/foo")
- => "~rms/foo"
- ;; The following example applies to VMS only.
- (file-name-sans-versions "foo;23")
- => "foo"
-
- - Function: file-name-sans-extension filename
- This function returns FILENAME minus its "extension," if any. The
- extension, in a file name, is the part that starts with the last
- `.' in the last name component. For example,
-
- (file-name-sans-extension "foo.lose.c")
- => "foo.lose"
- (file-name-sans-extension "big.hack/foo")
- => "big.hack/foo"
-
-\1f
-File: lispref.info, Node: Directory Names, Next: Relative File Names, Prev: File Name Components, Up: File Names
-
-Directory Names
----------------
-
- A "directory name" is the name of a directory. A directory is a
-kind of file, and it has a file name, which is related to the directory
-name but not identical to it. (This is not quite the same as the usual
-Unix terminology.) These two different names for the same entity are
-related by a syntactic transformation. On Unix, this is simple: a
-directory name ends in a slash, whereas the directory's name as a file
-lacks that slash. On VMS, the relationship is more complicated.
-
- The difference between a directory name and its name as a file is
-subtle but crucial. When an XEmacs variable or function argument is
-described as being a directory name, a file name of a directory is not
-acceptable.
-
- The following two functions convert between directory names and file
-names. They do nothing special with environment variable substitutions
-such as `$HOME', and the constructs `~', and `..'.
-
- - Function: file-name-as-directory filename
- This function returns a string representing FILENAME in a form
- that the operating system will interpret as the name of a
- directory. In Unix, this means appending a slash to the string.
- On VMS, the function converts a string of the form `[X]Y.DIR.1' to
- the form `[X.Y]'.
-
- (file-name-as-directory "~rms/lewis")
- => "~rms/lewis/"
-
- - Function: directory-file-name dirname
- This function returns a string representing DIRNAME in a form that
- the operating system will interpret as the name of a file. On
- Unix, this means removing a final slash from the string. On VMS,
- the function converts a string of the form `[X.Y]' to `[X]Y.DIR.1'.
-
- (directory-file-name "~lewis/")
- => "~lewis"
-
- Directory name abbreviations are useful for directories that are
-normally accessed through symbolic links. Sometimes the users recognize
-primarily the link's name as "the name" of the directory, and find it
-annoying to see the directory's "real" name. If you define the link
-name as an abbreviation for the "real" name, XEmacs shows users the
-abbreviation instead.
-
- If you wish to convert a directory name to its abbreviation, use this
-function:
-
- - Function: abbreviate-file-name dirname &optional hack-homedir
- This function applies abbreviations from `directory-abbrev-alist'
- to its argument, and substitutes `~' for the user's home directory.
-
- If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for
- the user's home directory.
-
-
- - Variable: directory-abbrev-alist
- The variable `directory-abbrev-alist' contains an alist of
- abbreviations to use for file directories. Each element has the
- form `(FROM . TO)', and says to replace FROM with TO when it
- appears in a directory name. The FROM string is actually a
- regular expression; it should always start with `^'. The function
- `abbreviate-file-name' performs these substitutions.
-
- You can set this variable in `site-init.el' to describe the
- abbreviations appropriate for your site.
-
- Here's an example, from a system on which file system `/home/fsf'
- and so on are normally accessed through symbolic links named `/fsf'
- and so on.
-
- (("^/home/fsf" . "/fsf")
- ("^/home/gp" . "/gp")
- ("^/home/gd" . "/gd"))
-
-\1f
-File: lispref.info, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names
-
-Absolute and Relative File Names
---------------------------------
-
- All the directories in the file system form a tree starting at the
-root directory. A file name can specify all the directory names
-starting from the root of the tree; then it is called an "absolute"
-file name. Or it can specify the position of the file in the tree
-relative to a default directory; then it is called a "relative" file
-name. On Unix, an absolute file name starts with a slash or a tilde
-(`~'), and a relative one does not. The rules on VMS are complicated.
-
- - Function: file-name-absolute-p filename
- This function returns `t' if file FILENAME is an absolute file
- name, `nil' otherwise. On VMS, this function understands both
- Unix syntax and VMS syntax.
-
- (file-name-absolute-p "~rms/foo")
- => t
- (file-name-absolute-p "rms/foo")
- => nil
- (file-name-absolute-p "/user/rms/foo")
- => t
-
-\1f
-File: lispref.info, Node: File Name Expansion, Next: Unique File Names, Prev: Relative File Names, Up: File Names
-
-Functions that Expand Filenames
--------------------------------
-
- "Expansion" of a file name means converting a relative file name to
-an absolute one. Since this is done relative to a default directory,
-you must specify the default directory name as well as the file name to
-be expanded. Expansion also simplifies file names by eliminating
-redundancies such as `./' and `NAME/../'.
-
- - Function: expand-file-name filename &optional directory
- This function converts FILENAME to an absolute file name. If
- DIRECTORY is supplied, it is the directory to start with if
- FILENAME is relative. (The value of DIRECTORY should itself be an
- absolute directory name; it may start with `~'.) Otherwise, the
- current buffer's value of `default-directory' is used. For
- example:
-
- (expand-file-name "foo")
- => "/xcssun/users/rms/lewis/foo"
- (expand-file-name "../foo")
- => "/xcssun/users/rms/foo"
- (expand-file-name "foo" "/usr/spool/")
- => "/usr/spool/foo"
- (expand-file-name "$HOME/foo")
- => "/xcssun/users/rms/lewis/$HOME/foo"
-
- Filenames containing `.' or `..' are simplified to their canonical
- form:
-
- (expand-file-name "bar/../foo")
- => "/xcssun/users/rms/lewis/foo"
-
- `~/' at the beginning is expanded into the user's home directory.
- A `/' or `~' following a `/'.
-
- Note that `expand-file-name' does _not_ expand environment
- variables; only `substitute-in-file-name' does that.
-
- - Function: file-relative-name filename &optional directory
- This function does the inverse of expansion--it tries to return a
- relative name that is equivalent to FILENAME when interpreted
- relative to DIRECTORY.
-
- If DIRECTORY is `nil' or omitted, the value of `default-directory'
- is used.
-
- (file-relative-name "/foo/bar" "/foo/")
- => "bar")
- (file-relative-name "/foo/bar" "/hack/")
- => "../foo/bar")
-
- - Variable: default-directory
- The value of this buffer-local variable is the default directory
- for the current buffer. It should be an absolute directory name;
- it may start with `~'. This variable is local in every buffer.
-
- `expand-file-name' uses the default directory when its second
- argument is `nil'.
-
- On Unix systems, the value is always a string ending with a slash.
-
- default-directory
- => "/user/lewis/manual/"
-
- - Function: substitute-in-file-name filename
- This function replaces environment variable references in FILENAME
- with the environment variable values. Following standard Unix
- shell syntax, `$' is the prefix to substitute an environment
- variable value.
-
- The environment variable name is the series of alphanumeric
- characters (including underscores) that follow the `$'. If the
- character following the `$' is a `{', then the variable name is
- everything up to the matching `}'.
-
- Here we assume that the environment variable `HOME', which holds
- the user's home directory name, has value `/xcssun/users/rms'.
-
- (substitute-in-file-name "$HOME/foo")
- => "/xcssun/users/rms/foo"
-
- After substitution, a `/' or `~' following a `/' is taken to be
- the start of an absolute file name that overrides what precedes
- it, so everything before that `/' or `~' is deleted. For example:
-
- (substitute-in-file-name "bar/~/foo")
- => "~/foo"
- (substitute-in-file-name "/usr/local/$HOME/foo")
- => "/xcssun/users/rms/foo"
-
- On VMS, `$' substitution is not done, so this function does nothing
- on VMS except discard superfluous initial components as shown
- above.
-
-\1f
-File: lispref.info, Node: Unique File Names, Next: File Name Completion, Prev: File Name Expansion, Up: File Names
-
-Generating Unique File Names
-----------------------------
-
- Some programs need to write temporary files. Here is the usual way
-to construct a name for such a file:
-
- (make-temp-name (expand-file-name NAME-OF-APPLICATION (temp-directory)))
-
-Here we use `(temp-directory)' to specify a directory for temporary
-files--under Unix, it will normally evaluate to `"/tmp/"'. The job of
-`make-temp-name' is to prevent two different users or two different
-processes from trying to use the same name.
-
- - Function: temp-directory
- This function returns the name of the directory to use for
- temporary files. Under Unix, this will be the value of `TMPDIR',
- defaulting to `/tmp'. On Windows, this will be obtained from the
- `TEMP' or `TMP' environment variables, defaulting to `/'.
-
- Note that the `temp-directory' function does not exist under FSF
- Emacs.
-
- - Function: make-temp-name prefix
- This function generates a temporary file name starting with
- PREFIX. The Emacs process number forms part of the result, so
- there is no danger of generating a name being used by another
- process.
-
- (make-temp-name "/tmp/foo")
- => "/tmp/fooGaAQjC"
-
- In addition, this function makes an attempt to choose a name that
- does not specify an existing file. To make this work, PREFIX
- should be an absolute file name.
-
- To avoid confusion, each Lisp application should preferably use a
- unique PREFIX to `make-temp-name'.
-
-\1f
-File: lispref.info, Node: File Name Completion, Next: User Name Completion, Prev: Unique File Names, Up: File Names
-
-File Name Completion
---------------------
-
- This section describes low-level subroutines for completing a file
-name. For other completion functions, see *Note Completion::.
-
- - Function: file-name-all-completions partial-filename directory
- This function returns a list of all possible completions for a file
- whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
- The order of the completions is the order of the files in the
- directory, which is unpredictable and conveys no useful
- information.
-
- The argument PARTIAL-FILENAME must be a file name containing no
- directory part and no slash. The current buffer's default
- directory is prepended to DIRECTORY, if DIRECTORY is not absolute.
-
- In the following example, suppose that the current default
- directory, `~rms/lewis', has five files whose names begin with `f':
- `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
-
- (file-name-all-completions "f" "")
- => ("foo" "file~" "file.c.~2~"
- "file.c.~1~" "file.c")
-
- (file-name-all-completions "fo" "")
- => ("foo")
-
- - Function: file-name-completion filename directory
- This function completes the file name FILENAME in directory
- DIRECTORY. It returns the longest prefix common to all file names
- in directory DIRECTORY that start with FILENAME.
-
- If only one match exists and FILENAME matches it exactly, the
- function returns `t'. The function returns `nil' if directory
- DIRECTORY contains no name starting with FILENAME.
-
- In the following example, suppose that the current default
- directory has five files whose names begin with `f': `foo',
- `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
-
- (file-name-completion "fi" "")
- => "file"
-
- (file-name-completion "file.c.~1" "")
- => "file.c.~1~"
-
- (file-name-completion "file.c.~1~" "")
- => t
-
- (file-name-completion "file.c.~3" "")
- => nil
-
- - User Option: completion-ignored-extensions
- `file-name-completion' usually ignores file names that end in any
- string in this list. It does not ignore them when all the possible
- completions end in one of these suffixes or when a buffer showing
- all possible completions is displayed.
-
- A typical value might look like this:
-
- completion-ignored-extensions
- => (".o" ".elc" "~" ".dvi")
-
-\1f
-File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names
-
-User Name Completion
---------------------
-
- This section describes low-level subroutines for completing a user
-name. For other completion functions, see *Note Completion::.
-
- - Function: user-name-all-completions partial-username
- This function returns a list of all possible completions for a user
- whose name starts with PARTIAL-USERNAME. The order of the
- completions is unpredictable and conveys no useful information.
-
- The argument PARTIAL-USERNAME must be a partial user name
- containing no tilde character and no slash.
-
- - Function: user-name-completion username
- This function completes the user name USERNAME. It returns the
- longest prefix common to all user names that start with USERNAME.
-
- If only one match exists and USERNAME matches it exactly, the
- function returns `t'. The function returns `nil' if no user name
- starting with USERNAME exists.
-
- - Function: user-name-completion-1 username
- This function completes the user name USERNAME, like
- `user-name-completion', differing only in the return value. This
- function returns the cons of the completion returned by
- `user-name-completion', and a boolean indicating whether that
- completion was unique.
-
-\1f
-File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files
-
-Contents of Directories
-=======================
-
- A directory is a kind of file that contains other files entered under
-various names. Directories are a feature of the file system.
-
- XEmacs can list the names of the files in a directory as a Lisp list,
-or display the names in a buffer using the `ls' shell command. In the
-latter case, it can optionally display information about each file,
-depending on the value of switches passed to the `ls' command.
-
- - Function: directory-files directory &optional full-name match-regexp
- nosort files-only
- This function returns a list of the names of the files in the
- directory DIRECTORY. By default, the list is in alphabetical
- order.
-
- If FULL-NAME is non-`nil', the function returns the files'
- absolute file names. Otherwise, it returns just the names
- relative to the specified directory.
-
- If MATCH-REGEXP is non-`nil', this function returns only those
- file names that contain that regular expression--the other file
- names are discarded from the list.
-
- If NOSORT is non-`nil', `directory-files' does not sort the list,
- so you get the file names in no particular order. Use this if you
- want the utmost possible speed and don't care what order the files
- are processed in. If the order of processing is visible to the
- user, then the user will probably be happier if you do sort the
- names.
-
- If FILES-ONLY is the symbol `t', then only the "files" in the
- directory will be returned; subdirectories will be excluded. If
- FILES-ONLY is not `nil' and not `t', then only the subdirectories
- will be returned. Otherwise, if FILES-ONLY is `nil' (the default)
- then both files and subdirectories will be returned.
-
- (directory-files "~lewis")
- => ("#foo#" "#foo.el#" "." ".."
- "dired-mods.el" "files.texi"
- "files.texi.~1~")
-
- An error is signaled if DIRECTORY is not the name of a directory
- that can be read.
-
- - Function: insert-directory file switches &optional wildcard
- full-directory-p
- This function inserts (in the current buffer) a directory listing
- for directory FILE, formatted with `ls' according to SWITCHES. It
- leaves point after the inserted text.
-
- The argument FILE may be either a directory name or a file
- specification including wildcard characters. If WILDCARD is
- non-`nil', that means treat FILE as a file specification with
- wildcards.
-
- If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
- and switches do not contain `-d', so that the listing should show
- the full contents of the directory. (The `-d' option to `ls' says
- to describe a directory itself rather than its contents.)
-
- This function works by running a directory listing program whose
- name is in the variable `insert-directory-program'. If WILDCARD is
- non-`nil', it also runs the shell specified by `shell-file-name',
- to expand the wildcards.
-
- - Variable: insert-directory-program
- This variable's value is the program to run to generate a
- directory listing for the function `insert-directory'.
-
-\1f
-File: lispref.info, Node: Create/Delete Dirs, Next: Magic File Names, Prev: Contents of Directories, Up: Files
-
-Creating and Deleting Directories
-=================================
-
- Most XEmacs Lisp file-manipulation functions get errors when used on
-files that are directories. For example, you cannot delete a directory
-with `delete-file'. These special functions exist to create and delete
-directories.
-
- - Command: make-directory dirname &optional parents
- This function creates a directory named DIRNAME. Interactively,
- the default choice of directory to create is the current default
- directory for file names. That is useful when you have visited a
- file in a nonexistent directory.
-
- Non-interactively, optional argument PARENTS says whether to
- create parent directories if they don't exist. (Interactively, this
- always happens.)
-
- - Command: delete-directory dirname
- This function deletes the directory named DIRNAME. The function
- `delete-file' does not work for files that are directories; you
- must use `delete-directory' in that case.
-
-\1f
-File: lispref.info, Node: Magic File Names, Next: Partial Files, Prev: Create/Delete Dirs, Up: Files
-
-Making Certain File Names "Magic"
-=================================
-
- You can implement special handling for certain file names. This is
-called making those names "magic". You must supply a regular
-expression to define the class of names (all those that match the
-regular expression), plus a handler that implements all the primitive
-XEmacs file operations for file names that do match.
-
- The variable `file-name-handler-alist' holds a list of handlers,
-together with regular expressions that determine when to apply each
-handler. Each element has this form:
-
- (REGEXP . HANDLER)
-
-All the XEmacs primitives for file access and file name transformation
-check the given file name against `file-name-handler-alist'. If the
-file name matches REGEXP, the primitives handle that file by calling
-HANDLER.
-
- The first argument given to HANDLER is the name of the primitive;
-the remaining arguments are the arguments that were passed to that
-operation. (The first of these arguments is typically the file name
-itself.) For example, if you do this:
-
- (file-exists-p FILENAME)
-
-and FILENAME has handler HANDLER, then HANDLER is called like this:
-
- (funcall HANDLER 'file-exists-p FILENAME)
-
- Here are the operations that a magic file name handler gets to
-handle:
-
-`add-name-to-file', `copy-file', `delete-directory', `delete-file',
-`diff-latest-backup-file', `directory-file-name', `directory-files',
-`dired-compress-file', `dired-uncache', `expand-file-name',
-`file-accessible-directory-p', `file-attributes', `file-directory-p',
-`file-executable-p', `file-exists-p', `file-local-copy', `file-modes',
-`file-name-all-completions', `file-name-as-directory',
-`file-name-completion', `file-name-directory', `file-name-nondirectory',
-`file-name-sans-versions', `file-newer-than-file-p', `file-readable-p',
-`file-regular-p', `file-symlink-p', `file-truename', `file-writable-p',
-`get-file-buffer', `insert-directory', `insert-file-contents', `load',
-`make-directory', `make-symbolic-link', `rename-file', `set-file-modes',
-`set-visited-file-modtime', `unhandled-file-name-directory',
-`verify-visited-file-modtime', `write-region'.
-
- Handlers for `insert-file-contents' typically need to clear the
-buffer's modified flag, with `(set-buffer-modified-p nil)', if the
-VISIT argument is non-`nil'. This also has the effect of unlocking the
-buffer if it is locked.
-
- The handler function must handle all of the above operations, and
-possibly others to be added in the future. It need not implement all
-these operations itself--when it has nothing special to do for a
-certain operation, it can reinvoke the primitive, to handle the
-operation "in the usual way". It should always reinvoke the primitive
-for an operation it does not recognize. Here's one way to do this:
-
- (defun my-file-handler (operation &rest args)
- ;; First check for the specific operations
- ;; that we have special handling for.
- (cond ((eq operation 'insert-file-contents) ...)
- ((eq operation 'write-region) ...)
- ...
- ;; Handle any operation we don't know about.
- (t (let ((inhibit-file-name-handlers
- (cons 'my-file-handler
- (and (eq inhibit-file-name-operation operation)
- inhibit-file-name-handlers)))
- (inhibit-file-name-operation operation))
- (apply operation args)))))
-
- When a handler function decides to call the ordinary Emacs primitive
-for the operation at hand, it needs to prevent the primitive from
-calling the same handler once again, thus leading to an infinite
-recursion. The example above shows how to do this, with the variables
-`inhibit-file-name-handlers' and `inhibit-file-name-operation'. Be
-careful to use them exactly as shown above; the details are crucial for
-proper behavior in the case of multiple handlers, and for operations
-that have two file names that may each have handlers.
-
- - Variable: inhibit-file-name-handlers
- This variable holds a list of handlers whose use is presently
- inhibited for a certain operation.
-
- - Variable: inhibit-file-name-operation
- The operation for which certain handlers are presently inhibited.
-
- - Function: find-file-name-handler file operation
- This function returns the handler function for file name FILE, or
- `nil' if there is none. The argument OPERATION should be the
- operation to be performed on the file--the value you will pass to
- the handler as its first argument when you call it. The operation
- is needed for comparison with `inhibit-file-name-operation'.
-
- - Function: file-local-copy filename
- This function copies file FILENAME to an ordinary non-magic file,
- if it isn't one already.
-
- If FILENAME specifies a "magic" file name, which programs outside
- Emacs cannot directly read or write, this copies the contents to
- an ordinary file and returns that file's name.
-
- If FILENAME is an ordinary file name, not magic, then this function
- does nothing and returns `nil'.
-
- - Function: unhandled-file-name-directory filename
- This function returns the name of a directory that is not magic.
- It uses the directory part of FILENAME if that is not magic.
- Otherwise, it asks the handler what to do.
-
- This is useful for running a subprocess; every subprocess must
- have a non-magic directory to serve as its current directory, and
- this function is a good way to come up with one.
-
-\1f
-File: lispref.info, Node: Partial Files, Next: Format Conversion, Prev: Magic File Names, Up: Files
-
-Partial Files
-=============
-
-* Menu:
-
-* Intro to Partial Files::
-* Creating a Partial File::
-* Detached Partial Files::
-
-\1f
-File: lispref.info, Node: Intro to Partial Files, Next: Creating a Partial File, Up: Partial Files
-
-Intro to Partial Files
-----------------------
-
- A "partial file" is a section of a buffer (called the "master
-buffer") that is placed in its own buffer and treated as its own file.
-Changes made to the partial file are not reflected in the master buffer
-until the partial file is "saved" using the standard buffer save
-commands. Partial files can be "reverted" (from the master buffer)
-just like normal files. When a file part is active on a master buffer,
-that section of the master buffer is marked as read-only. Two file
-parts on the same master buffer are not allowed to overlap. Partial
-file buffers are indicated by the words `File Part' in the modeline.
-
- The master buffer knows about all the partial files that are active
-on it, and thus killing or reverting the master buffer will be handled
-properly. When the master buffer is saved, if there are any unsaved
-partial files active on it then the user will be given the opportunity
-to first save these files.
-
- When a partial file buffer is first modified, the master buffer is
-automatically marked as modified so that saving the master buffer will
-work correctly.
-
-\1f
-File: lispref.info, Node: Creating a Partial File, Next: Detached Partial Files, Prev: Intro to Partial Files, Up: Partial Files
-
-Creating a Partial File
------------------------
-
- - Function: make-file-part &optional start end name buffer
- Make a file part on buffer BUFFER out of the region. Call it
- NAME. This command creates a new buffer containing the contents
- of the region and marks the buffer as referring to the specified
- buffer, called the "master buffer". When the file-part buffer is
- saved, its changes are integrated back into the master buffer.
- When the master buffer is deleted, all file parts are deleted with
- it.
-
- When called from a function, expects four arguments, START, END,
- NAME, and BUFFER, all of which are optional and default to the
- beginning of BUFFER, the end of BUFFER, a name generated from
- BUFFER name, and the current buffer, respectively.
-
-\1f
-File: lispref.info, Node: Detached Partial Files, Prev: Creating a Partial File, Up: Partial Files
-
-Detached Partial Files
-----------------------
-
- Every partial file has an extent in the master buffer associated
-with it (called the "master extent"), marking where in the master
-buffer the partial file begins and ends. If the text in master buffer
-that is contained by the extent is deleted, then the extent becomes
-"detached", meaning that it no longer refers to a specific region of
-the master buffer. This can happen either when the text is deleted
-directly or when the master buffer is reverted. Neither of these should
-happen in normal usage because the master buffer should generally not be
-edited directly.
-
- Before doing any operation that references a partial file's master
-extent, XEmacs checks to make sure that the extent is not detached. If
-this is the case, XEmacs warns the user of this and the master extent is
-deleted out of the master buffer, disconnecting the file part. The file
-part's filename is cleared and thus must be explicitly specified if the
-detached file part is to be saved.
-
-\1f
-File: lispref.info, Node: Format Conversion, Next: Files and MS-DOS, Prev: Partial Files, Up: Files
-
-File Format Conversion
-======================
-
- The variable `format-alist' defines a list of "file formats", which
-describe textual representations used in files for the data (text,
-text-properties, and possibly other information) in an Emacs buffer.
-Emacs performs format conversion if appropriate when reading and writing
-files.
-
- - Variable: format-alist
- This list contains one format definition for each defined file
- format.
-
- Each format definition is a list of this form:
-
- (NAME DOC-STRING REGEXP FROM-FN TO-FN MODIFY MODE-FN)
-
- Here is what the elements in a format definition mean:
-
-NAME
- The name of this format.
-
-DOC-STRING
- A documentation string for the format.
-
-REGEXP
- A regular expression which is used to recognize files represented
- in this format.
-
-FROM-FN
- A function to call to decode data in this format (to convert file
- data into the usual Emacs data representation).
-
- The FROM-FN is called with two args, BEGIN and END, which specify
- the part of the buffer it should convert. It should convert the
- text by editing it in place. Since this can change the length of
- the text, FROM-FN should return the modified end position.
-
- One responsibility of FROM-FN is to make sure that the beginning
- of the file no longer matches REGEXP. Otherwise it is likely to
- get called again.
-
-TO-FN
- A function to call to encode data in this format (to convert the
- usual Emacs data representation into this format).
-
- The TO-FN is called with two args, BEGIN and END, which specify
- the part of the buffer it should convert. There are two ways it
- can do the conversion:
-
- * By editing the buffer in place. In this case, TO-FN should
- return the end-position of the range of text, as modified.
-
- * By returning a list of annotations. This is a list of
- elements of the form `(POSITION . STRING)', where POSITION is
- an integer specifying the relative position in the text to be
- written, and STRING is the annotation to add there. The list
- must be sorted in order of position when TO-FN returns it.
-
- When `write-region' actually writes the text from the buffer
- to the file, it intermixes the specified annotations at the
- corresponding positions. All this takes place without
- modifying the buffer.
-
-MODIFY
- A flag, `t' if the encoding function modifies the buffer, and
- `nil' if it works by returning a list of annotations.
-
-MODE
- A mode function to call after visiting a file converted from this
- format.
-
- The function `insert-file-contents' automatically recognizes file
-formats when it reads the specified file. It checks the text of the
-beginning of the file against the regular expressions of the format
-definitions, and if it finds a match, it calls the decoding function for
-that format. Then it checks all the known formats over again. It
-keeps checking them until none of them is applicable.
-
- Visiting a file, with `find-file-noselect' or the commands that use
-it, performs conversion likewise (because it calls
-`insert-file-contents'); it also calls the mode function for each
-format that it decodes. It stores a list of the format names in the
-buffer-local variable `buffer-file-format'.
-
- - Variable: buffer-file-format
- This variable states the format of the visited file. More
- precisely, this is a list of the file format names that were
- decoded in the course of visiting the current buffer's file. It
- is always local in all buffers.
-
- When `write-region' writes data into a file, it first calls the
-encoding functions for the formats listed in `buffer-file-format', in
-the order of appearance in the list.
-
- - Function: format-write-file file format
- This command writes the current buffer contents into the file FILE
- in format FORMAT, and makes that format the default for future
- saves of the buffer. The argument FORMAT is a list of format
- names.
-
- - Function: format-find-file file format
- This command finds the file FILE, converting it according to
- format FORMAT. It also makes FORMAT the default if the buffer is
- saved later.
-
- The argument FORMAT is a list of format names. If FORMAT is
- `nil', no conversion takes place. Interactively, typing just
- <RET> for FORMAT specifies `nil'.
-
- - Function: format-insert-file file format &optional beg end
- This command inserts the contents of file FILE, converting it
- according to format FORMAT. If BEG and END are non-`nil', they
- specify which part of the file to read, as in
- `insert-file-contents' (*note Reading from Files::).
-
- The return value is like what `insert-file-contents' returns: a
- list of the absolute file name and the length of the data inserted
- (after conversion).
-
- The argument FORMAT is a list of format names. If FORMAT is
- `nil', no conversion takes place. Interactively, typing just
- <RET> for FORMAT specifies `nil'.
-
- - Function: format-find-file file format
- This command finds the file FILE, converting it according to
- format FORMAT. It also makes FORMAT the default if the buffer is
- saved later.
-
- The argument FORMAT is a list of format names. If FORMAT is
- `nil', no conversion takes place. Interactively, typing just
- <RET> for FORMAT specifies `nil'.
-
- - Function: format-insert-file file format &optional beg end
- This command inserts the contents of file FILE, converting it
- according to format FORMAT. If BEG and END are non-`nil', they
- specify which part of the file to read, as in
- `insert-file-contents' (*note Reading from Files::).
-
- The return value is like what `insert-file-contents' returns: a
- list of the absolute file name and the length of the data inserted
- (after conversion).
-
- The argument FORMAT is a list of format names. If FORMAT is
- `nil', no conversion takes place. Interactively, typing just
- <RET> for FORMAT specifies `nil'.
-
- - Variable: auto-save-file-format
- This variable specifies the format to use for auto-saving. Its
- value is a list of format names, just like the value of
- `buffer-file-format'; but it is used instead of
- `buffer-file-format' for writing auto-save files. This variable
- is always local in all buffers.
-
projects / chise / xemacs-chise.git / blobdiff