annotate lispref/files.texi @ 10100:461530f66e34

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