X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-23;h=fa5cce66ddd0331218eb13d8f071850839e1d0f7;hb=7c20beeb0e0dae144d6cb5785761366d9b5c369a;hp=6f4fb8669fde5e04d88717b4f5e95cbf6405a2c0;hpb=7d6edaefa00e7b7e102354283824a4f6a721b71a;p=chise%2Fxemacs-chise.git- diff --git a/info/lispref.info-23 b/info/lispref.info-23 index 6f4fb86..fa5cce6 100644 --- a/info/lispref.info-23 +++ b/info/lispref.info-23 @@ -50,6 +50,936 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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'. + + +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'. + + +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. + + +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. + + +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") + => # + + - 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. + + +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") + => # + (create-file-buffer "foo") + => #> + (create-file-buffer "foo") + => #> + + 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'. + + +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. + + +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::. + + +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. + + +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'. + + +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. + + +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::. + + +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). + + +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. + + File: lispref.info, Node: File Attributes, Prev: Truenames, Up: Information about Files Other Information about Files @@ -206,1053 +1136,3 @@ and modification. `-32252' is on file system number -32252. - -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'. - - -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. - - -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" - - -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")) - - -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 - - -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. - - -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'. - - -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") - - -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. - - -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'. - - -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. - - -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. - - -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:: - - -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. - - -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. - - -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. - - -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 - 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 - 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 - 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 - 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. -