Mercurial > emacs
annotate lispref/files.texi @ 79723:ec9cfc111df0
*** empty log message ***
author | Nick Roberts <nickrob@snap.net.nz> |
---|---|
date | Mon, 07 Jan 2008 03:49:07 +0000 |
parents | cf24d1dc433c |
children | a1e16e813aed 776cb0a1bb24 |
rev | line source |
---|---|
6555 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
75250
6d19c76d81c5
Update copyright for years from Emacs 21 to present (mainly adding
Glenn Morris <rgm@gnu.org>
parents:
74688
diff
changeset
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, |
6d19c76d81c5
Update copyright for years from Emacs 21 to present (mainly adding
Glenn Morris <rgm@gnu.org>
parents:
74688
diff
changeset
|
4 @c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. |
6555 | 5 @c See the file elisp.texi for copying conditions. |
6 @setfilename ../info/files | |
7 @node Files, Backups and Auto-Saving, Documentation, Top | |
8 @comment node-name, next, previous, up | |
9 @chapter Files | |
10 | |
11 In Emacs, you can find, create, view, save, and otherwise work with | |
12 files and file directories. This chapter describes most of the | |
13 file-related functions of Emacs Lisp, but a few others are described in | |
14 @ref{Buffers}, and those related to backups and auto-saving are | |
15 described in @ref{Backups and Auto-Saving}. | |
16 | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
17 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
|
18 names. A file name is actually a string. Most of these functions |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
19 expand file name arguments by calling @code{expand-file-name}, so that |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
20 @file{~} is handled correctly, as are relative file names (including |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
21 @samp{../}). These functions don't recognize environment variable |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
22 substitutions such as @samp{$HOME}. @xref{File Name Expansion}. |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
23 |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
24 When file I/O functions signal Lisp errors, they usually use the |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
25 condition @code{file-error} (@pxref{Handling Errors}). The error |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
26 message is in most cases obtained from the operating system, according |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
27 to locale @code{system-message-locale}, and decoded using coding system |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
28 @code{locale-coding-system} (@pxref{Locales}). |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
29 |
6555 | 30 @menu |
31 * Visiting Files:: Reading files into Emacs buffers for editing. | |
32 * Saving Buffers:: Writing changed buffers back into files. | |
33 * Reading from Files:: Reading files into buffers without visiting. | |
34 * Writing to Files:: Writing new files from parts of buffers. | |
35 * File Locks:: Locking and unlocking files, to prevent | |
36 simultaneous editing by two people. | |
37 * Information about Files:: Testing existence, accessibility, size of files. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
38 * Changing Files:: Renaming files, changing protection, etc. |
6555 | 39 * File Names:: Decomposing and expanding file names. |
40 * Contents of Directories:: Getting a list of the files in a directory. | |
41 * Create/Delete Dirs:: Creating and Deleting Directories. | |
42 * Magic File Names:: Defining "magic" special handling | |
43 for certain file names. | |
12067 | 44 * Format Conversion:: Conversion to and from various file formats. |
6555 | 45 @end menu |
46 | |
47 @node Visiting Files | |
48 @section Visiting Files | |
49 @cindex finding files | |
50 @cindex visiting files | |
51 | |
52 Visiting a file means reading a file into a buffer. Once this is | |
53 done, we say that the buffer is @dfn{visiting} that file, and call the | |
54 file ``the visited file'' of the buffer. | |
55 | |
56 A file and a buffer are two different things. A file is information | |
57 recorded permanently in the computer (unless you delete it). A buffer, | |
58 on the other hand, is information inside of Emacs that will vanish at | |
59 the end of the editing session (or when you kill the buffer). Usually, | |
60 a buffer contains information that you have copied from a file; then we | |
61 say the buffer is visiting that file. The copy in the buffer is what | |
62 you modify with editing commands. Such changes to the buffer do not | |
63 change the file; therefore, to make the changes permanent, you must | |
64 @dfn{save} the buffer, which means copying the altered buffer contents | |
65 back into the file. | |
66 | |
67 In spite of the distinction between files and buffers, people often | |
68 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
|
69 ``I am editing a file,'' rather than, ``I am editing a buffer that I |
6555 | 70 will soon save as a file of the same name.'' Humans do not usually need |
71 to make the distinction explicit. When dealing with a computer program, | |
72 however, it is good to keep the distinction in mind. | |
73 | |
74 @menu | |
75 * Visiting Functions:: The usual interface functions for visiting. | |
76 * Subroutines of Visiting:: Lower-level subroutines that they use. | |
77 @end menu | |
78 | |
79 @node Visiting Functions | |
80 @subsection Functions for Visiting Files | |
81 | |
82 This section describes the functions normally used to visit files. | |
83 For historical reasons, these functions have names starting with | |
84 @samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for | |
85 functions and variables that access the visited file name of a buffer or | |
86 that find an existing buffer by its visited file name. | |
87 | |
12098 | 88 In a Lisp program, if you want to look at the contents of a file but |
89 not alter it, the fastest way is to use @code{insert-file-contents} in a | |
90 temporary buffer. Visiting the file is not necessary and takes longer. | |
91 @xref{Reading from Files}. | |
92 | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
93 @deffn Command find-file filename &optional wildcards |
6555 | 94 This command selects a buffer visiting the file @var{filename}, |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
47980
diff
changeset
|
95 using an existing buffer if there is one, and otherwise creating a |
6555 | 96 new buffer and reading the file into it. It also returns that buffer. |
97 | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
98 Aside from some technical details, the body of the @code{find-file} |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
99 function is basically equivalent to: |
6555 | 100 |
63583
99e9892a51d9
Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents:
62856
diff
changeset
|
101 @smallexample |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
102 (switch-to-buffer (find-file-noselect filename nil nil wildcards)) |
63583
99e9892a51d9
Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents:
62856
diff
changeset
|
103 @end smallexample |
6555 | 104 |
105 @noindent | |
106 (See @code{switch-to-buffer} in @ref{Displaying Buffers}.) | |
107 | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
108 If @var{wildcards} is non-@code{nil}, which is always true in an |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
109 interactive call, then @code{find-file} expands wildcard characters in |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
110 @var{filename} and visits all the matching files. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
111 |
6555 | 112 When @code{find-file} is called interactively, it prompts for |
113 @var{filename} in the minibuffer. | |
114 @end deffn | |
115 | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
116 @defun find-file-noselect filename &optional nowarn rawfile wildcards |
70657
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
117 This function is the guts of all the file-visiting functions. It |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
118 returns a buffer visiting the file @var{filename}. You may make the |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
119 buffer current or display it in a window if you wish, but this |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
120 function does not do so. |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
121 |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
122 The function returns an existing buffer if there is one; otherwise it |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
123 creates a new buffer and reads the file into it. When |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
124 @code{find-file-noselect} uses an existing buffer, it first verifies |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
125 that the file has not changed since it was last visited or saved in |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
126 that buffer. If the file has changed, this function asks the user |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
127 whether to reread the changed file. If the user says @samp{yes}, any |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
128 edits previously made in the buffer are lost. |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
129 |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
130 Reading the file involves decoding the file's contents (@pxref{Coding |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
131 Systems}), including end-of-line conversion, and format conversion |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
132 (@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil}, |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
133 then @code{find-file-noselect} expands wildcard characters in |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
134 @var{filename} and visits all the matching files. |
6555 | 135 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
136 This function displays warning or advisory messages in various peculiar |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
137 cases, unless the optional argument @var{nowarn} is non-@code{nil}. For |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
138 example, if it needs to create a buffer, and there is no file named |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
139 @var{filename}, it displays the message @samp{(New file)} in the echo |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
140 area, and leaves the buffer empty. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
141 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
142 The @code{find-file-noselect} function normally calls |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
143 @code{after-find-file} after reading the file (@pxref{Subroutines of |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
144 Visiting}). That function sets the buffer major mode, parses local |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
145 variables, warns the user if there exists an auto-save file more recent |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
146 than the file just visited, and finishes by running the functions in |
45979
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
147 @code{find-file-hook}. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
148 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
149 If the optional argument @var{rawfile} is non-@code{nil}, then |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
150 @code{after-find-file} is not called, and the |
70657
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
151 @code{find-file-not-found-functions} are not run in case of failure. |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
152 What's more, a non-@code{nil} @var{rawfile} value suppresses coding |
9a270d0b2af7
(Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents:
70624
diff
changeset
|
153 system conversion and format conversion. |
6555 | 154 |
32842
b10fc3a9befa
(Visiting Functions): Return value of find-file-noselect may be a list
Kenichi Handa <handa@m17n.org>
parents:
30501
diff
changeset
|
155 The @code{find-file-noselect} function usually returns the buffer that |
b10fc3a9befa
(Visiting Functions): Return value of find-file-noselect may be a list
Kenichi Handa <handa@m17n.org>
parents:
30501
diff
changeset
|
156 is visiting the file @var{filename}. But, if wildcards are actually |
32859
7600e7ac0dcd
(Visiting Functions): Typos.
Gerd Moellmann <gerd@gnu.org>
parents:
32842
diff
changeset
|
157 used and expanded, it returns a list of buffers that are visiting the |
32842
b10fc3a9befa
(Visiting Functions): Return value of find-file-noselect may be a list
Kenichi Handa <handa@m17n.org>
parents:
30501
diff
changeset
|
158 various files. |
6555 | 159 |
160 @example | |
161 @group | |
162 (find-file-noselect "/etc/fstab") | |
163 @result{} #<buffer fstab> | |
164 @end group | |
165 @end example | |
166 @end defun | |
167 | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
168 @deffn Command find-file-other-window filename &optional wildcards |
6555 | 169 This command selects a buffer visiting the file @var{filename}, but |
170 does so in a window other than the selected window. It may use another | |
171 existing window or split a window; see @ref{Displaying Buffers}. | |
172 | |
173 When this command is called interactively, it prompts for | |
174 @var{filename}. | |
175 @end deffn | |
176 | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
177 @deffn Command find-file-read-only filename &optional wildcards |
6555 | 178 This command selects a buffer visiting the file @var{filename}, like |
179 @code{find-file}, but it marks the buffer as read-only. @xref{Read Only | |
180 Buffers}, for related functions and variables. | |
181 | |
182 When this command is called interactively, it prompts for | |
183 @var{filename}. | |
184 @end deffn | |
185 | |
186 @deffn Command view-file filename | |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
187 This command visits @var{filename} using View mode, returning to the |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
188 previous buffer when you exit View mode. View mode is a minor mode that |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
189 provides commands to skim rapidly through the file, but does not let you |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
190 modify the text. Entering View mode runs the normal hook |
12098 | 191 @code{view-mode-hook}. @xref{Hooks}. |
6555 | 192 |
193 When @code{view-file} is called interactively, it prompts for | |
194 @var{filename}. | |
195 @end deffn | |
196 | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
197 @defopt find-file-wildcards |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
198 If this variable is non-@code{nil}, then the various @code{find-file} |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
199 commands check for wildcard characters and visit all the files that |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
200 match them (when invoked interactively or when their @var{wildcards} |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
201 argument is non-@code{nil}). If this option is @code{nil}, then |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
202 the @code{find-file} commands ignore their @var{wildcards} argument |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
203 and never treat wildcard characters specially. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
204 @end defopt |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
205 |
45979
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
206 @defvar find-file-hook |
6555 | 207 The value of this variable is a list of functions to be called after a |
208 file is visited. The file's local-variables specification (if any) will | |
209 have been processed before the hooks are run. The buffer visiting the | |
210 file is current when the hook functions are run. | |
211 | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
212 This variable is a normal hook. @xref{Hooks}. |
6555 | 213 @end defvar |
214 | |
45979
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
215 @defvar find-file-not-found-functions |
6555 | 216 The value of this variable is a list of functions to be called when |
217 @code{find-file} or @code{find-file-noselect} is passed a nonexistent | |
218 file name. @code{find-file-noselect} calls these functions as soon as | |
219 it detects a nonexistent file. It calls them in the order of the list, | |
220 until one of them returns non-@code{nil}. @code{buffer-file-name} is | |
221 already set up. | |
222 | |
223 This is not a normal hook because the values of the functions are | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
224 used, and in many cases only some of the functions are called. |
6555 | 225 @end defvar |
226 | |
227 @node Subroutines of Visiting | |
228 @comment node-name, next, previous, up | |
229 @subsection Subroutines of Visiting | |
230 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
231 The @code{find-file-noselect} function uses two important subroutines |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
232 which are sometimes useful in user Lisp code: @code{create-file-buffer} |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
233 and @code{after-find-file}. This section explains how to use them. |
6555 | 234 |
235 @defun create-file-buffer filename | |
236 This function creates a suitably named buffer for visiting | |
237 @var{filename}, and returns it. It uses @var{filename} (sans directory) | |
238 as the name if that name is free; otherwise, it appends a string such as | |
239 @samp{<2>} to get an unused name. See also @ref{Creating Buffers}. | |
240 | |
241 @strong{Please note:} @code{create-file-buffer} does @emph{not} | |
242 associate the new buffer with a file and does not select the buffer. | |
12098 | 243 It also does not use the default major mode. |
6555 | 244 |
245 @example | |
246 @group | |
247 (create-file-buffer "foo") | |
248 @result{} #<buffer foo> | |
249 @end group | |
250 @group | |
251 (create-file-buffer "foo") | |
252 @result{} #<buffer foo<2>> | |
253 @end group | |
254 @group | |
255 (create-file-buffer "foo") | |
256 @result{} #<buffer foo<3>> | |
257 @end group | |
258 @end example | |
259 | |
260 This function is used by @code{find-file-noselect}. | |
261 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}). | |
262 @end defun | |
263 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
264 @defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes |
6555 | 265 This function sets the buffer major mode, and parses local variables |
266 (@pxref{Auto Major Mode}). It is called by @code{find-file-noselect} | |
267 and by the default revert function (@pxref{Reverting}). | |
268 | |
269 @cindex new file message | |
270 @cindex file open error | |
271 If reading the file got an error because the file does not exist, but | |
272 its directory does exist, the caller should pass a non-@code{nil} value | |
273 for @var{error}. In that case, @code{after-find-file} issues a warning: | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
274 @samp{(New file)}. For more serious errors, the caller should usually not |
6555 | 275 call @code{after-find-file}. |
276 | |
277 If @var{warn} is non-@code{nil}, then this function issues a warning | |
278 if an auto-save file exists and is more recent than the visited file. | |
279 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
280 If @var{noauto} is non-@code{nil}, that says not to enable or disable |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
281 Auto-Save mode. The mode remains enabled if it was enabled before. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
282 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
283 If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
284 means this call was from @code{revert-buffer}. This has no direct |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
285 effect, but some mode functions and hook functions check the value |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
286 of this variable. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
287 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
288 If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
289 major mode, don't process local variables specifications in the file, |
45979
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
290 and don't run @code{find-file-hook}. This feature is used by |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
291 @code{revert-buffer} in some cases. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
292 |
6555 | 293 The last thing @code{after-find-file} does is call all the functions |
45979
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
294 in the list @code{find-file-hook}. |
6555 | 295 @end defun |
296 | |
297 @node Saving Buffers | |
298 @section Saving Buffers | |
76841 | 299 @cindex saving buffers |
6555 | 300 |
301 When you edit a file in Emacs, you are actually working on a buffer | |
302 that is visiting that file---that is, the contents of the file are | |
303 copied into the buffer and the copy is what you edit. Changes to the | |
304 buffer do not change the file until you @dfn{save} the buffer, which | |
305 means copying the contents of the buffer into the file. | |
306 | |
307 @deffn Command save-buffer &optional backup-option | |
308 This function saves the contents of the current buffer in its visited | |
309 file if the buffer has been modified since it was last visited or saved. | |
310 Otherwise it does nothing. | |
311 | |
312 @code{save-buffer} is responsible for making backup files. Normally, | |
313 @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
|
314 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
|
315 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
|
316 other circumstances: |
6555 | 317 |
318 @itemize @bullet | |
319 @item | |
320 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the | |
321 @code{save-buffer} function marks this version of the file to be | |
322 backed up when the buffer is next saved. | |
323 | |
324 @item | |
325 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the | |
326 @code{save-buffer} function unconditionally backs up the previous | |
327 version of the file before saving it. | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
328 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
329 @item |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
330 With an argument of 0, unconditionally do @emph{not} make any backup file. |
6555 | 331 @end itemize |
332 @end deffn | |
333 | |
56215 | 334 @deffn Command save-some-buffers &optional save-silently-p pred |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
335 @anchor{Definition of save-some-buffers} |
6555 | 336 This command saves some modified file-visiting buffers. Normally it |
337 asks the user about each buffer. But if @var{save-silently-p} is | |
338 non-@code{nil}, it saves all the file-visiting buffers without querying | |
339 the user. | |
340 | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
341 The optional @var{pred} argument controls which buffers to ask about |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
342 (or to save silently if @var{save-silently-p} is non-@code{nil}). |
26770
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
343 If it is @code{nil}, that means to ask only about file-visiting buffers. |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
344 If it is @code{t}, that means also offer to save certain other non-file |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
345 buffers---those that have a non-@code{nil} buffer-local value of |
65369
822218f80ae4
2005-09-08 Chong Yidong <cyd@stupidchicken.com>
Chong Yidong <cyd@stupidchicken.com>
parents:
65248
diff
changeset
|
346 @code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says |
822218f80ae4
2005-09-08 Chong Yidong <cyd@stupidchicken.com>
Chong Yidong <cyd@stupidchicken.com>
parents:
65248
diff
changeset
|
347 @samp{yes} to saving a non-file buffer is asked to specify the file |
65437
035ea9e34f56
2005-09-10 Chong Yidong <cyd@stupidchicken.com>
Chong Yidong <cyd@stupidchicken.com>
parents:
65369
diff
changeset
|
348 name to use. The @code{save-buffers-kill-emacs} function passes the |
65369
822218f80ae4
2005-09-08 Chong Yidong <cyd@stupidchicken.com>
Chong Yidong <cyd@stupidchicken.com>
parents:
65248
diff
changeset
|
349 value @code{t} for @var{pred}. |
26770
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
350 |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
351 If @var{pred} is neither @code{t} nor @code{nil}, then it should be |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
352 a function of no arguments. It will be called in each buffer to decide |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
353 whether to offer to save that buffer. If it returns a non-@code{nil} |
2d8554ed8748
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
354 value in a certain buffer, that means do offer to save that buffer. |
6555 | 355 @end deffn |
356 | |
56215 | 357 @deffn Command write-file filename &optional confirm |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
358 @anchor{Definition of write-file} |
6555 | 359 This function writes the current buffer into file @var{filename}, makes |
360 the buffer visit that file, and marks it not modified. Then it renames | |
361 the buffer based on @var{filename}, appending a string like @samp{<2>} | |
362 if necessary to make a unique buffer name. It does most of this work by | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
363 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
364 @code{save-buffer}. |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
365 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
366 If @var{confirm} is non-@code{nil}, that means to ask for confirmation |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
367 before overwriting an existing file. Interactively, confirmation is |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
368 required, unless the user supplies a prefix argument. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
369 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
370 If @var{filename} is an existing directory, or a symbolic link to one, |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
371 @code{write-file} uses the name of the visited file, in directory |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
372 @var{filename}. If the buffer is not visiting a file, it uses the |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
373 buffer name instead. |
6555 | 374 @end deffn |
375 | |
15913
f415fdc67ad3
Add xrefs from Saving Buffers to Format Conversion and Saving
Richard M. Stallman <rms@gnu.org>
parents:
15765
diff
changeset
|
376 Saving a buffer runs several hooks. It also performs format |
f415fdc67ad3
Add xrefs from Saving Buffers to Format Conversion and Saving
Richard M. Stallman <rms@gnu.org>
parents:
15765
diff
changeset
|
377 conversion (@pxref{Format Conversion}), and may save text properties in |
f415fdc67ad3
Add xrefs from Saving Buffers to Format Conversion and Saving
Richard M. Stallman <rms@gnu.org>
parents:
15765
diff
changeset
|
378 ``annotations'' (@pxref{Saving Properties}). |
f415fdc67ad3
Add xrefs from Saving Buffers to Format Conversion and Saving
Richard M. Stallman <rms@gnu.org>
parents:
15765
diff
changeset
|
379 |
45979
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
380 @defvar write-file-functions |
6555 | 381 The value of this variable is a list of functions to be called before |
382 writing out a buffer to its visited file. If one of them returns | |
383 non-@code{nil}, the file is considered already written and the rest of | |
384 the functions are not called, nor is the usual code for writing the file | |
385 executed. | |
386 | |
45979
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
387 If a function in @code{write-file-functions} returns non-@code{nil}, it |
6555 | 388 is responsible for making a backup file (if that is appropriate). |
389 To do so, execute the following code: | |
390 | |
391 @example | |
392 (or buffer-backed-up (backup-buffer)) | |
393 @end example | |
394 | |
395 You might wish to save the file modes value returned by | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
396 @code{backup-buffer} and use that (if non-@code{nil}) to set the mode |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
397 bits of the file that you write. This is what @code{save-buffer} |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
398 normally does. @xref{Making Backups,, Making Backup Files}. |
6555 | 399 |
70624
97f1ae99fe30
(Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents:
70538
diff
changeset
|
400 The hook functions in @code{write-file-functions} are also responsible |
97f1ae99fe30
(Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents:
70538
diff
changeset
|
401 for encoding the data (if desired): they must choose a suitable coding |
97f1ae99fe30
(Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents:
70538
diff
changeset
|
402 system and end-of-line conversion (@pxref{Lisp and Coding Systems}), |
97f1ae99fe30
(Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents:
70538
diff
changeset
|
403 perform the encoding (@pxref{Explicit Encoding}), and set |
97f1ae99fe30
(Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents:
70538
diff
changeset
|
404 @code{last-coding-system-used} to the coding system that was used |
97f1ae99fe30
(Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents:
70538
diff
changeset
|
405 (@pxref{Encoding and I/O}). |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
406 |
45979
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
407 If you set this hook locally in a buffer, it is assumed to be |
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
408 associated with the file or the way the contents of the buffer were |
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
409 obtained. Thus the variable is marked as a permanent local, so that |
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
410 changing the major mode does not alter a buffer-local value. On the |
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
411 other hand, calling @code{set-visited-file-name} will reset it. |
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
412 If this is not what you want, you might like to use |
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
413 @code{write-contents-functions} instead. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
414 |
6555 | 415 Even though this is not a normal hook, you can use @code{add-hook} and |
416 @code{remove-hook} to manipulate the list. @xref{Hooks}. | |
417 @end defvar | |
418 | |
419 @c Emacs 19 feature | |
45979
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
420 @defvar write-contents-functions |
56322
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
421 This works just like @code{write-file-functions}, but it is intended |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
422 for hooks that pertain to the buffer's contents, not to the particular |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
423 visited file or its location. Such hooks are usually set up by major |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
424 modes, as buffer-local bindings for this variable. This variable |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
425 automatically becomes buffer-local whenever it is set; switching to a |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
426 new major mode always resets this variable, but calling |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
427 @code{set-visited-file-name} does not. |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
428 |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
429 If any of the functions in this hook returns non-@code{nil}, the file |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
430 is considered already written and the rest are not called and neither |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
431 are the functions in @code{write-file-functions}. |
6555 | 432 @end defvar |
433 | |
53531
5bd5de5e98c2
(Saving Buffers): Clarify descriptions of `write-contents-functions'
Luc Teirlinck <teirllm@auburn.edu>
parents:
53505
diff
changeset
|
434 @defopt before-save-hook |
5bd5de5e98c2
(Saving Buffers): Clarify descriptions of `write-contents-functions'
Luc Teirlinck <teirllm@auburn.edu>
parents:
53505
diff
changeset
|
435 This normal hook runs before a buffer is saved in its visited file, |
5bd5de5e98c2
(Saving Buffers): Clarify descriptions of `write-contents-functions'
Luc Teirlinck <teirllm@auburn.edu>
parents:
53505
diff
changeset
|
436 regardless of whether that is done normally or by one of the hooks |
53575
a679a0134e06
*** empty log message ***
Luc Teirlinck <teirllm@auburn.edu>
parents:
53531
diff
changeset
|
437 described above. For instance, the @file{copyright.el} program uses |
a679a0134e06
*** empty log message ***
Luc Teirlinck <teirllm@auburn.edu>
parents:
53531
diff
changeset
|
438 this hook to make sure the file you are saving has the current year in |
a679a0134e06
*** empty log message ***
Luc Teirlinck <teirllm@auburn.edu>
parents:
53531
diff
changeset
|
439 its copyright notice. |
53531
5bd5de5e98c2
(Saving Buffers): Clarify descriptions of `write-contents-functions'
Luc Teirlinck <teirllm@auburn.edu>
parents:
53505
diff
changeset
|
440 @end defopt |
53505
780b9eb8b58e
hooks.texi (Standard Hooks): Add before-save-hook.
Simon Josefsson <jas@extundo.com>
parents:
53425
diff
changeset
|
441 |
6555 | 442 @c Emacs 19 feature |
53531
5bd5de5e98c2
(Saving Buffers): Clarify descriptions of `write-contents-functions'
Luc Teirlinck <teirllm@auburn.edu>
parents:
53505
diff
changeset
|
443 @defopt after-save-hook |
6555 | 444 This normal hook runs after a buffer has been saved in its visited file. |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
445 One use of this hook is in Fast Lock mode; it uses this hook to save the |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
446 highlighting information in a cache file. |
53531
5bd5de5e98c2
(Saving Buffers): Clarify descriptions of `write-contents-functions'
Luc Teirlinck <teirllm@auburn.edu>
parents:
53505
diff
changeset
|
447 @end defopt |
6555 | 448 |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
449 @defopt file-precious-flag |
6555 | 450 If this variable is non-@code{nil}, then @code{save-buffer} protects |
451 against I/O errors while saving by writing the new file to a temporary | |
452 name instead of the name it is supposed to have, and then renaming it to | |
453 the intended name after it is clear there are no errors. This procedure | |
454 prevents problems such as a lack of disk space from resulting in an | |
455 invalid file. | |
456 | |
12226 | 457 As a side effect, backups are necessarily made by copying. @xref{Rename |
458 or Copy}. Yet, at the same time, saving a precious file always breaks | |
459 all hard links between the file you save and other file names. | |
6555 | 460 |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
461 Some modes give this variable a non-@code{nil} buffer-local value |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
462 in particular buffers. |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
463 @end defopt |
6555 | 464 |
465 @defopt require-final-newline | |
466 This variable determines whether files may be written out that do | |
467 @emph{not} end with a newline. If the value of the variable is | |
468 @code{t}, then @code{save-buffer} silently adds a newline at the end of | |
469 the file whenever the buffer being saved does not already end in one. | |
470 If the value of the variable is non-@code{nil}, but not @code{t}, then | |
471 @code{save-buffer} asks the user whether to add a newline each time the | |
472 case arises. | |
473 | |
474 If the value of the variable is @code{nil}, then @code{save-buffer} | |
475 doesn't add newlines at all. @code{nil} is the default value, but a few | |
476 major modes set it to @code{t} in particular buffers. | |
477 @end defopt | |
478 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
479 See also the function @code{set-visited-file-name} (@pxref{Buffer File |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
480 Name}). |
15765
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
481 |
6555 | 482 @node Reading from Files |
483 @comment node-name, next, previous, up | |
484 @section Reading from Files | |
76841 | 485 @cindex reading from files |
6555 | 486 |
487 You can copy a file from the disk and insert it into a buffer | |
488 using the @code{insert-file-contents} function. Don't use the user-level | |
489 command @code{insert-file} in a Lisp program, as that sets the mark. | |
490 | |
491 @defun insert-file-contents filename &optional visit beg end replace | |
492 This function inserts the contents of file @var{filename} into the | |
12226 | 493 current buffer after point. It returns a list of the absolute file name |
6555 | 494 and the length of the data inserted. An error is signaled if |
495 @var{filename} is not the name of a file that can be read. | |
496 | |
12098 | 497 The function @code{insert-file-contents} checks the file contents |
498 against the defined file formats, and converts the file contents if | |
499 appropriate. @xref{Format Conversion}. It also calls the functions in | |
500 the list @code{after-insert-file-functions}; see @ref{Saving | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
501 Properties}. Normally, one of the functions in the |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
502 @code{after-insert-file-functions} list determines the coding system |
70624
97f1ae99fe30
(Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents:
70538
diff
changeset
|
503 (@pxref{Coding Systems}) used for decoding the file's contents, |
97f1ae99fe30
(Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents:
70538
diff
changeset
|
504 including end-of-line conversion. |
6555 | 505 |
506 If @var{visit} is non-@code{nil}, this function additionally marks the | |
507 buffer as unmodified and sets up various fields in the buffer so that it | |
508 is visiting the file @var{filename}: these include the buffer's visited | |
509 file name and its last save file modtime. This feature is used by | |
510 @code{find-file-noselect} and you probably should not use it yourself. | |
511 | |
512 If @var{beg} and @var{end} are non-@code{nil}, they should be integers | |
513 specifying the portion of the file to insert. In this case, @var{visit} | |
514 must be @code{nil}. For example, | |
515 | |
516 @example | |
517 (insert-file-contents filename nil 0 500) | |
518 @end example | |
519 | |
520 @noindent | |
521 inserts the first 500 characters of a file. | |
522 | |
523 If the argument @var{replace} is non-@code{nil}, it means to replace the | |
524 contents of the buffer (actually, just the accessible portion) with the | |
525 contents of the file. This is better than simply deleting the buffer | |
526 contents and inserting the whole file, because (1) it preserves some | |
527 marker positions and (2) it puts less data in the undo list. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
528 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
529 It is possible to read a special file (such as a FIFO or an I/O device) |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
530 with @code{insert-file-contents}, as long as @var{replace} and |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
531 @var{visit} are @code{nil}. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
532 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
533 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
534 @defun insert-file-contents-literally filename &optional visit beg end replace |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
535 This function works like @code{insert-file-contents} except that it does |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
536 not do format decoding (@pxref{Format Conversion}), does not do |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
537 character code conversion (@pxref{Coding Systems}), does not run |
45979
87962bf716e3
*** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
40188
diff
changeset
|
538 @code{find-file-hook}, does not perform automatic uncompression, and so |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
539 on. |
6555 | 540 @end defun |
541 | |
542 If you want to pass a file name to another process so that another | |
543 program can read the file, use the function @code{file-local-copy}; see | |
544 @ref{Magic File Names}. | |
545 | |
546 @node Writing to Files | |
547 @comment node-name, next, previous, up | |
548 @section Writing to Files | |
76841 | 549 @cindex writing to files |
6555 | 550 |
551 You can write the contents of a buffer, or part of a buffer, directly | |
552 to a file on disk using the @code{append-to-file} and | |
553 @code{write-region} functions. Don't use these functions to write to | |
554 files that are being visited; that could cause confusion in the | |
555 mechanisms for visiting. | |
556 | |
557 @deffn Command append-to-file start end filename | |
558 This function appends the contents of the region delimited by | |
559 @var{start} and @var{end} in the current buffer to the end of file | |
560 @var{filename}. If that file does not exist, it is created. This | |
561 function returns @code{nil}. | |
562 | |
563 An error is signaled if @var{filename} specifies a nonwritable file, | |
564 or a nonexistent file in a directory where files cannot be created. | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
565 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
566 When called from Lisp, this function is completely equivalent to: |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
567 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
568 @example |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
569 (write-region start end filename t) |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
570 @end example |
6555 | 571 @end deffn |
572 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
573 @deffn Command write-region start end filename &optional append visit lockname mustbenew |
6555 | 574 This function writes the region delimited by @var{start} and @var{end} |
575 in the current buffer into the file specified by @var{filename}. | |
576 | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
577 If @var{start} is @code{nil}, then the command writes the entire buffer |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
578 contents (@emph{not} just the accessible portion) to the file and |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
579 ignores @var{end}. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
580 |
6555 | 581 @c Emacs 19 feature |
582 If @var{start} is a string, then @code{write-region} writes or appends | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
583 that string, rather than text from the buffer. @var{end} is ignored in |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
584 this case. |
6555 | 585 |
586 If @var{append} is non-@code{nil}, then the specified text is appended | |
60444
78a2cd972ba1
(Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents:
59877
diff
changeset
|
587 to the existing file contents (if any). If @var{append} is an |
78a2cd972ba1
(Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents:
59877
diff
changeset
|
588 integer, @code{write-region} seeks to that byte offset from the start |
78a2cd972ba1
(Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents:
59877
diff
changeset
|
589 of the file and writes the data from there. |
6555 | 590 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
591 If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks |
60444
78a2cd972ba1
(Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents:
59877
diff
changeset
|
592 for confirmation if @var{filename} names an existing file. If |
78a2cd972ba1
(Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents:
59877
diff
changeset
|
593 @var{mustbenew} is the symbol @code{excl}, then @code{write-region} |
78a2cd972ba1
(Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents:
59877
diff
changeset
|
594 does not ask for confirmation, but instead it signals an error |
78a2cd972ba1
(Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents:
59877
diff
changeset
|
595 @code{file-already-exists} if the file already exists. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
596 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
597 The test for an existing file, when @var{mustbenew} is @code{excl}, uses |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
598 a special system feature. At least for files on a local disk, there is |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
599 no chance that some other program could create a file of the same name |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
600 before Emacs does, without Emacs's noticing. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
601 |
6555 | 602 If @var{visit} is @code{t}, then Emacs establishes an association |
603 between the buffer and the file: the buffer is then visiting that file. | |
604 It also sets the last file modification time for the current buffer to | |
605 @var{filename}'s modtime, and marks the buffer as not modified. This | |
606 feature is used by @code{save-buffer}, but you probably should not use | |
607 it yourself. | |
608 | |
609 @c Emacs 19 feature | |
610 If @var{visit} is a string, it specifies the file name to visit. This | |
611 way, you can write the data to one file (@var{filename}) while recording | |
612 the buffer as visiting another file (@var{visit}). The argument | |
613 @var{visit} is used in the echo area message and also for file locking; | |
614 @var{visit} is stored in @code{buffer-file-name}. This feature is used | |
615 to implement @code{file-precious-flag}; don't use it yourself unless you | |
616 really know what you're doing. | |
617 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
618 The optional argument @var{lockname}, if non-@code{nil}, specifies the |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
619 file name to use for purposes of locking and unlocking, overriding |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
620 @var{filename} and @var{visit} for that purpose. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
621 |
12098 | 622 The function @code{write-region} converts the data which it writes to |
623 the appropriate file formats specified by @code{buffer-file-format}. | |
624 @xref{Format Conversion}. It also calls the functions in the list | |
625 @code{write-region-annotate-functions}; see @ref{Saving Properties}. | |
6555 | 626 |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
627 Normally, @code{write-region} displays the message @samp{Wrote |
6555 | 628 @var{filename}} in the echo area. If @var{visit} is neither @code{t} |
629 nor @code{nil} nor a string, then this message is inhibited. This | |
630 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
|
631 files that the user does not need to know about. |
6555 | 632 @end deffn |
633 | |
66144
d14adceeb897
(Writing to Files): Replace `...' with `@dots{}' in `@defmac' and `@defspec'.
Juri Linkov <juri@jurta.org>
parents:
65437
diff
changeset
|
634 @defmac with-temp-file file body@dots{} |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
635 @anchor{Definition of with-temp-file} |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
636 The @code{with-temp-file} macro evaluates the @var{body} forms with a |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
637 temporary buffer as the current buffer; then, at the end, it writes the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
638 buffer contents into file @var{file}. It kills the temporary buffer |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
639 when finished, restoring the buffer that was current before the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
640 @code{with-temp-file} form. Then it returns the value of the last form |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
641 in @var{body}. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
642 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
643 The current buffer is restored even in case of an abnormal exit via |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
644 @code{throw} or error (@pxref{Nonlocal Exits}). |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
645 |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
646 See also @code{with-temp-buffer} in @ref{Definition of |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
647 with-temp-buffer,, The Current Buffer}. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
648 @end defmac |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
649 |
6555 | 650 @node File Locks |
651 @section File Locks | |
652 @cindex file locks | |
76841 | 653 @cindex lock file |
6555 | 654 |
59877
36a927615e6d
(File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents:
56981
diff
changeset
|
655 When two users edit the same file at the same time, they are likely |
36a927615e6d
(File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents:
56981
diff
changeset
|
656 to interfere with each other. Emacs tries to prevent this situation |
36a927615e6d
(File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents:
56981
diff
changeset
|
657 from arising by recording a @dfn{file lock} when a file is being |
36a927615e6d
(File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents:
56981
diff
changeset
|
658 modified. (File locks are not implemented on Microsoft systems.) |
6555 | 659 Emacs can then detect the first attempt to modify a buffer visiting a |
660 file that is locked by another Emacs job, and ask the user what to do. | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
661 The file lock is really a file, a symbolic link with a special name, |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
662 stored in the same directory as the file you are editing. |
6555 | 663 |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
664 When you access files using NFS, there may be a small probability that |
71957
61cb5aae3bc3
Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents:
71709
diff
changeset
|
665 you and another user will both lock the same file ``simultaneously.'' |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
666 If this happens, it is possible for the two users to make changes |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
667 simultaneously, but Emacs will still warn the user who saves second. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
668 Also, the detection of modification of a buffer visiting a file changed |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
669 on disk catches some cases of simultaneous editing; see |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
670 @ref{Modification Time}. |
6555 | 671 |
672 @defun file-locked-p filename | |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
673 This function returns @code{nil} if the file @var{filename} is not |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
674 locked. It returns @code{t} if it is locked by this Emacs process, and |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
675 it returns the name of the user who has locked it if it is locked by |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
676 some other job. |
6555 | 677 |
678 @example | |
679 @group | |
680 (file-locked-p "foo") | |
681 @result{} nil | |
682 @end group | |
683 @end example | |
684 @end defun | |
685 | |
686 @defun lock-buffer &optional filename | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
687 This function locks the file @var{filename}, if the current buffer is |
6555 | 688 modified. The argument @var{filename} defaults to the current buffer's |
689 visited file. Nothing is done if the current buffer is not visiting a | |
59877
36a927615e6d
(File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents:
56981
diff
changeset
|
690 file, or is not modified, or if the system does not support locking. |
6555 | 691 @end defun |
692 | |
693 @defun unlock-buffer | |
694 This function unlocks the file being visited in the current buffer, | |
695 if the buffer is modified. If the buffer is not modified, then | |
696 the file should not be locked, so this function does nothing. It also | |
59877
36a927615e6d
(File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents:
56981
diff
changeset
|
697 does nothing if the current buffer is not visiting a file, or if the |
36a927615e6d
(File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents:
56981
diff
changeset
|
698 system does not support locking. |
6555 | 699 @end defun |
700 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
701 File locking is not supported on some systems. On systems that do not |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
702 support it, the functions @code{lock-buffer}, @code{unlock-buffer} and |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
703 @code{file-locked-p} do nothing and return @code{nil}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
704 |
6555 | 705 @defun ask-user-about-lock file other-user |
706 This function is called when the user tries to modify @var{file}, but it | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
707 is locked by another user named @var{other-user}. The default |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
708 definition of this function asks the user to say what to do. The value |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
709 this function returns determines what Emacs does next: |
6555 | 710 |
711 @itemize @bullet | |
712 @item | |
713 A value of @code{t} says to grab the lock on the file. Then | |
714 this user may edit the file and @var{other-user} loses the lock. | |
715 | |
716 @item | |
717 A value of @code{nil} says to ignore the lock and let this | |
718 user edit the file anyway. | |
719 | |
720 @item | |
721 @kindex file-locked | |
722 This function may instead signal a @code{file-locked} error, in which | |
723 case the change that the user was about to make does not take place. | |
724 | |
725 The error message for this error looks like this: | |
726 | |
727 @example | |
728 @error{} File is locked: @var{file} @var{other-user} | |
729 @end example | |
730 | |
731 @noindent | |
732 where @code{file} is the name of the file and @var{other-user} is the | |
733 name of the user who has locked the file. | |
734 @end itemize | |
735 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
736 If you wish, you can replace the @code{ask-user-about-lock} function |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
737 with your own version that makes the decision in another way. The code |
6555 | 738 for its usual definition is in @file{userlock.el}. |
739 @end defun | |
740 | |
741 @node Information about Files | |
742 @section Information about Files | |
76841 | 743 @cindex file, information about |
6555 | 744 |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
745 The functions described in this section all operate on strings that |
62585
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
746 designate file names. With a few exceptions, all the functions have |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
747 names that begin with the word @samp{file}. These functions all |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
748 return information about actual files or directories, so their |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
749 arguments must all exist as actual files or directories unless |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
750 otherwise noted. |
6555 | 751 |
752 @menu | |
753 * Testing Accessibility:: Is a given file readable? Writable? | |
754 * Kinds of Files:: Is it a directory? A symbolic link? | |
755 * Truenames:: Eliminating symbolic links from a file name. | |
756 * File Attributes:: How large is it? Any other names? Etc. | |
62585
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
757 * Locating Files:: How to find a file in standard places. |
6555 | 758 @end menu |
759 | |
760 @node Testing Accessibility | |
761 @comment node-name, next, previous, up | |
762 @subsection Testing Accessibility | |
763 @cindex accessibility of a file | |
764 @cindex file accessibility | |
765 | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
766 These functions test for permission to access a file in specific |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
767 ways. Unless explicitly stated otherwise, they recursively follow |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
768 symbolic links for their file name arguments, at all levels (at the |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
769 level of the file itself and at all levels of parent directories). |
6555 | 770 |
771 @defun file-exists-p filename | |
51654
24b62b8f3def
Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents:
51558
diff
changeset
|
772 This function returns @code{t} if a file named @var{filename} appears |
24b62b8f3def
Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents:
51558
diff
changeset
|
773 to exist. This does not mean you can necessarily read the file, only |
24b62b8f3def
Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents:
51558
diff
changeset
|
774 that you can find out its attributes. (On Unix and GNU/Linux, this is |
24b62b8f3def
Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents:
51558
diff
changeset
|
775 true if the file exists and you have execute permission on the |
24b62b8f3def
Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents:
51558
diff
changeset
|
776 containing directories, regardless of the protection of the file |
24b62b8f3def
Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents:
51558
diff
changeset
|
777 itself.) |
6555 | 778 |
779 If the file does not exist, or if fascist access control policies | |
780 prevent you from finding the attributes of the file, this function | |
781 returns @code{nil}. | |
51654
24b62b8f3def
Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents:
51558
diff
changeset
|
782 |
24b62b8f3def
Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents:
51558
diff
changeset
|
783 Directories are files, so @code{file-exists-p} returns @code{t} when |
24b62b8f3def
Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents:
51558
diff
changeset
|
784 given a directory name. However, symbolic links are treated |
24b62b8f3def
Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents:
51558
diff
changeset
|
785 specially; @code{file-exists-p} returns @code{t} for a symbolic link |
24b62b8f3def
Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents:
51558
diff
changeset
|
786 name only if the target file exists. |
6555 | 787 @end defun |
788 | |
789 @defun file-readable-p filename | |
790 This function returns @code{t} if a file named @var{filename} exists | |
791 and you can read it. It returns @code{nil} otherwise. | |
792 | |
793 @example | |
794 @group | |
795 (file-readable-p "files.texi") | |
796 @result{} t | |
797 @end group | |
798 @group | |
799 (file-exists-p "/usr/spool/mqueue") | |
800 @result{} t | |
801 @end group | |
802 @group | |
803 (file-readable-p "/usr/spool/mqueue") | |
804 @result{} nil | |
805 @end group | |
806 @end example | |
807 @end defun | |
808 | |
809 @c Emacs 19 feature | |
810 @defun file-executable-p filename | |
811 This function returns @code{t} if a file named @var{filename} exists and | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
812 you can execute it. It returns @code{nil} otherwise. On Unix and |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
813 GNU/Linux, if the file is a directory, execute permission means you can |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
814 check the existence and attributes of files inside the directory, and |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
815 open those files if their modes permit. |
6555 | 816 @end defun |
817 | |
818 @defun file-writable-p filename | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
819 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
|
820 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
|
821 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
|
822 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
|
823 directory. |
6555 | 824 |
825 In the third example below, @file{foo} is not writable because the | |
826 parent directory does not exist, even though the user could create such | |
827 a directory. | |
828 | |
829 @example | |
830 @group | |
831 (file-writable-p "~/foo") | |
832 @result{} t | |
833 @end group | |
834 @group | |
835 (file-writable-p "/foo") | |
836 @result{} nil | |
837 @end group | |
838 @group | |
839 (file-writable-p "~/no-such-dir/foo") | |
840 @result{} nil | |
841 @end group | |
842 @end example | |
843 @end defun | |
844 | |
845 @c Emacs 19 feature | |
846 @defun file-accessible-directory-p dirname | |
847 This function returns @code{t} if you have permission to open existing | |
59877
36a927615e6d
(File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents:
56981
diff
changeset
|
848 files in the directory whose name as a file is @var{dirname}; |
36a927615e6d
(File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents:
56981
diff
changeset
|
849 otherwise (or if there is no such directory), it returns @code{nil}. |
36a927615e6d
(File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents:
56981
diff
changeset
|
850 The value of @var{dirname} may be either a directory name (such as |
36a927615e6d
(File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents:
56981
diff
changeset
|
851 @file{/foo/}) or the file name of a file which is a directory |
36a927615e6d
(File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents:
56981
diff
changeset
|
852 (such as @file{/foo}, without the final slash). |
6555 | 853 |
854 Example: after the following, | |
855 | |
856 @example | |
857 (file-accessible-directory-p "/foo") | |
858 @result{} nil | |
859 @end example | |
860 | |
861 @noindent | |
862 we can deduce that any attempt to read a file in @file{/foo/} will | |
863 give an error. | |
864 @end defun | |
865 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
866 @defun access-file filename string |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
867 This function opens file @var{filename} for reading, then closes it and |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
868 returns @code{nil}. However, if the open fails, it signals an error |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
869 using @var{string} as the error message text. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
870 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
871 |
12067 | 872 @defun file-ownership-preserved-p filename |
873 This function returns @code{t} if deleting the file @var{filename} and | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
874 then creating it anew would keep the file's owner unchanged. It also |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
875 returns @code{t} for nonexistent files. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
876 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
877 If @var{filename} is a symbolic link, then, unlike the other functions |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
878 discussed here, @code{file-ownership-preserved-p} does @emph{not} |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
879 replace @var{filename} with its target. However, it does recursively |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
880 follow symbolic links at all levels of parent directories. |
12067 | 881 @end defun |
882 | |
6555 | 883 @defun file-newer-than-file-p filename1 filename2 |
884 @cindex file age | |
885 @cindex file modification time | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
886 This function returns @code{t} if the file @var{filename1} is |
6555 | 887 newer than file @var{filename2}. If @var{filename1} does not |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
888 exist, it returns @code{nil}. If @var{filename1} does exist, but |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
889 @var{filename2} does not, it returns @code{t}. |
6555 | 890 |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
891 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
|
892 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
|
893 @file{no-file} doesn't exist at all. |
6555 | 894 |
895 @example | |
896 @group | |
897 (file-newer-than-file-p "aug-19" "aug-20") | |
898 @result{} nil | |
899 @end group | |
900 @group | |
901 (file-newer-than-file-p "aug-20" "aug-19") | |
902 @result{} t | |
903 @end group | |
904 @group | |
905 (file-newer-than-file-p "aug-19" "no-file") | |
906 @result{} t | |
907 @end group | |
908 @group | |
909 (file-newer-than-file-p "no-file" "aug-19") | |
910 @result{} nil | |
911 @end group | |
912 @end example | |
913 | |
914 You can use @code{file-attributes} to get a file's last modification | |
915 time as a list of two numbers. @xref{File Attributes}. | |
916 @end defun | |
917 | |
918 @node Kinds of Files | |
919 @comment node-name, next, previous, up | |
920 @subsection Distinguishing Kinds of Files | |
921 | |
12098 | 922 This section describes how to distinguish various kinds of files, such |
923 as directories, symbolic links, and ordinary files. | |
6555 | 924 |
925 @defun file-symlink-p filename | |
926 @cindex file symbolic links | |
50501
3bf63c244c44
(Kinds of Files): Correct return value of file-symlink-p.
Richard M. Stallman <rms@gnu.org>
parents:
49600
diff
changeset
|
927 If the file @var{filename} is a symbolic link, the |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
928 @code{file-symlink-p} function returns the (non-recursive) link target |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
929 as a string. (Determining the file name that the link points to from |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
930 the target is nontrivial.) First, this function recursively follows |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
931 symbolic links at all levels of parent directories. |
6555 | 932 |
933 If the file @var{filename} is not a symbolic link (or there is no such file), | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
47980
diff
changeset
|
934 @code{file-symlink-p} returns @code{nil}. |
6555 | 935 |
936 @example | |
937 @group | |
938 (file-symlink-p "foo") | |
939 @result{} nil | |
940 @end group | |
941 @group | |
942 (file-symlink-p "sym-link") | |
943 @result{} "foo" | |
944 @end group | |
945 @group | |
946 (file-symlink-p "sym-link2") | |
947 @result{} "sym-link" | |
948 @end group | |
949 @group | |
950 (file-symlink-p "/bin") | |
951 @result{} "/pub/bin" | |
952 @end group | |
953 @end example | |
954 | |
955 @c !!! file-symlink-p: should show output of ls -l for comparison | |
956 @end defun | |
957 | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
958 The next two functions recursively follow symbolic links at |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
959 all levels for @var{filename}. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
960 |
6555 | 961 @defun file-directory-p filename |
962 This function returns @code{t} if @var{filename} is the name of an | |
963 existing directory, @code{nil} otherwise. | |
964 | |
965 @example | |
966 @group | |
967 (file-directory-p "~rms") | |
968 @result{} t | |
969 @end group | |
970 @group | |
971 (file-directory-p "~rms/lewis/files.texi") | |
972 @result{} nil | |
973 @end group | |
974 @group | |
975 (file-directory-p "~rms/lewis/no-such-file") | |
976 @result{} nil | |
977 @end group | |
978 @group | |
979 (file-directory-p "$HOME") | |
980 @result{} nil | |
981 @end group | |
982 @group | |
983 (file-directory-p | |
984 (substitute-in-file-name "$HOME")) | |
985 @result{} t | |
986 @end group | |
987 @end example | |
988 @end defun | |
989 | |
12067 | 990 @defun file-regular-p filename |
991 This function returns @code{t} if the file @var{filename} exists and is | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
992 a regular file (not a directory, named pipe, terminal, or |
12067 | 993 other I/O device). |
994 @end defun | |
995 | |
6555 | 996 @node Truenames |
997 @subsection Truenames | |
998 @cindex truename (of file) | |
999 | |
1000 @c Emacs 19 features | |
1001 The @dfn{truename} of a file is the name that you get by following | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1002 symbolic links at all levels until none remain, then simplifying away |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1003 @samp{.}@: and @samp{..}@: appearing as name components. This results |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1004 in a sort of canonical name for the file. A file does not always have a |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1005 unique truename; the number of distinct truenames a file has is equal to |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1006 the number of hard links to the file. However, truenames are useful |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1007 because they eliminate symbolic links as a cause of name variation. |
6555 | 1008 |
1009 @defun file-truename filename | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1010 The function @code{file-truename} returns the truename of the file |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1011 @var{filename}. The argument must be an absolute file name. |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1012 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1013 This function does not expand environment variables. Only |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1014 @code{substitute-in-file-name} does that. @xref{Definition of |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1015 substitute-in-file-name}. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1016 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1017 If you may need to follow symbolic links preceding @samp{..}@: |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1018 appearing as a name component, you should make sure to call |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1019 @code{file-truename} without prior direct or indirect calls to |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1020 @code{expand-file-name}, as otherwise the file name component |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1021 immediately preceding @samp{..} will be ``simplified away'' before |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1022 @code{file-truename} is called. To eliminate the need for a call to |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1023 @code{expand-file-name}, @code{file-truename} handles @samp{~} in the |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1024 same way that @code{expand-file-name} does. @xref{File Name |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1025 Expansion,, Functions that Expand Filenames}. |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1026 @end defun |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1027 |
52003
0509fad02151
(Truenames): Add LIMIT arg to file-chase-links.
Richard M. Stallman <rms@gnu.org>
parents:
51913
diff
changeset
|
1028 @defun file-chase-links filename &optional limit |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1029 This function follows symbolic links, starting with @var{filename}, |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1030 until it finds a file name which is not the name of a symbolic link. |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1031 Then it returns that file name. This function does @emph{not} follow |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1032 symbolic links at the level of parent directories. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1033 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1034 If you specify a number for @var{limit}, then after chasing through |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1035 that many links, the function just returns what it has even if that is |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1036 still a symbolic link. |
6555 | 1037 @end defun |
1038 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1039 To illustrate the difference between @code{file-chase-links} and |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1040 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1041 the directory @file{/home/foo}, and @file{/home/foo/hello} is an |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1042 ordinary file (or at least, not a symbolic link) or nonexistent. Then |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1043 we would have: |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1044 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1045 @example |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1046 (file-chase-links "/usr/foo/hello") |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1047 ;; @r{This does not follow the links in the parent directories.} |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1048 @result{} "/usr/foo/hello" |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1049 (file-truename "/usr/foo/hello") |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1050 ;; @r{Assuming that @file{/home} is not a symbolic link.} |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1051 @result{} "/home/foo/hello" |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1052 @end example |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1053 |
6555 | 1054 @xref{Buffer File Name}, for related information. |
1055 | |
1056 @node File Attributes | |
1057 @comment node-name, next, previous, up | |
1058 @subsection Other Information about Files | |
1059 | |
1060 This section describes the functions for getting detailed information | |
1061 about a file, other than its contents. This information includes the | |
1062 mode bits that control access permission, the owner and group numbers, | |
1063 the number of names, the inode number, the size, and the times of access | |
1064 and modification. | |
1065 | |
1066 @defun file-modes filename | |
1067 @cindex permission | |
1068 @cindex file attributes | |
1069 This function returns the mode bits of @var{filename}, as an integer. | |
1070 The mode bits are also called the file permissions, and they specify | |
1071 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
|
1072 then the file is executable by all users, if the second-lowest-order bit |
6555 | 1073 is 1, then the file is writable by all users, etc. |
1074 | |
1075 The highest value returnable is 4095 (7777 octal), meaning that | |
52978
1a5c50faf357
Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents:
52401
diff
changeset
|
1076 everyone has read, write, and execute permission, that the @acronym{SUID} bit |
6555 | 1077 is set for both others and group, and that the sticky bit is set. |
1078 | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1079 If @var{filename} does not exist, @code{file-modes} returns @code{nil}. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1080 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1081 This function recursively follows symbolic links at all levels. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1082 |
6555 | 1083 @example |
1084 @group | |
1085 (file-modes "~/junk/diffs") | |
1086 @result{} 492 ; @r{Decimal integer.} | |
1087 @end group | |
1088 @group | |
1089 (format "%o" 492) | |
1090 @result{} "754" ; @r{Convert to octal.} | |
1091 @end group | |
1092 | |
1093 @group | |
1094 (set-file-modes "~/junk/diffs" 438) | |
1095 @result{} nil | |
1096 @end group | |
1097 | |
1098 @group | |
1099 (format "%o" 438) | |
1100 @result{} "666" ; @r{Convert to octal.} | |
1101 @end group | |
1102 | |
1103 @group | |
1104 % ls -l diffs | |
1105 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs | |
1106 @end group | |
1107 @end example | |
1108 @end defun | |
1109 | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1110 If the @var{filename} argument to the next two functions is a symbolic |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1111 link, then these function do @emph{not} replace it with its target. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1112 However, they both recursively follow symbolic links at all levels of |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1113 parent directories. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1114 |
6555 | 1115 @defun file-nlinks filename |
1116 This functions returns the number of names (i.e., hard links) that | |
1117 file @var{filename} has. If the file does not exist, then this function | |
1118 returns @code{nil}. Note that symbolic links have no effect on this | |
1119 function, because they are not considered to be names of the files they | |
1120 link to. | |
1121 | |
1122 @example | |
1123 @group | |
1124 % ls -l foo* | |
1125 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo | |
1126 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1 | |
1127 @end group | |
1128 | |
1129 @group | |
1130 (file-nlinks "foo") | |
1131 @result{} 2 | |
1132 @end group | |
1133 @group | |
1134 (file-nlinks "doesnt-exist") | |
1135 @result{} nil | |
1136 @end group | |
1137 @end example | |
1138 @end defun | |
1139 | |
56215 | 1140 @defun file-attributes filename &optional id-format |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1141 @anchor{Definition of file-attributes} |
6555 | 1142 This function returns a list of attributes of file @var{filename}. If |
1143 the specified file cannot be opened, it returns @code{nil}. | |
53109
420dc7ac8867
(File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents:
52978
diff
changeset
|
1144 The optional parameter @var{id-format} specifies the preferred format |
420dc7ac8867
(File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents:
52978
diff
changeset
|
1145 of attributes @acronym{UID} and @acronym{GID} (see below)---the |
420dc7ac8867
(File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents:
52978
diff
changeset
|
1146 valid values are @code{'string} and @code{'integer}. The latter is |
420dc7ac8867
(File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents:
52978
diff
changeset
|
1147 the default, but we plan to change that, so you should specify a |
420dc7ac8867
(File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents:
52978
diff
changeset
|
1148 non-@code{nil} value for @var{id-format} if you use the returned |
420dc7ac8867
(File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents:
52978
diff
changeset
|
1149 @acronym{UID} or @acronym{GID}. |
6555 | 1150 |
1151 The elements of the list, in order, are: | |
1152 | |
1153 @enumerate 0 | |
1154 @item | |
1155 @code{t} for a directory, a string for a symbolic link (the name | |
1156 linked to), or @code{nil} for a text file. | |
1157 | |
1158 @c Wordy so as to prevent an overfull hbox. --rjc 15mar92 | |
1159 @item | |
1160 The number of names the file has. Alternate names, also known as hard | |
1161 links, can be created by using the @code{add-name-to-file} function | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1162 (@pxref{Changing Files}). |
6555 | 1163 |
1164 @item | |
75476
330094c564c4
(File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents:
75250
diff
changeset
|
1165 The file's @acronym{UID}, normally as a string. However, if it does |
330094c564c4
(File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents:
75250
diff
changeset
|
1166 not correspond to a named user, the value is an integer or a floating |
330094c564c4
(File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents:
75250
diff
changeset
|
1167 point number. |
6555 | 1168 |
1169 @item | |
75476
330094c564c4
(File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents:
75250
diff
changeset
|
1170 The file's @acronym{GID}, likewise. |
6555 | 1171 |
1172 @item | |
1173 The time of last access, as a list of two integers. | |
1174 The first integer has the high-order 16 bits of time, | |
1175 the second has the low 16 bits. (This is similar to the | |
1176 value of @code{current-time}; see @ref{Time of Day}.) | |
1177 | |
1178 @item | |
1179 The time of last modification as a list of two integers (as above). | |
77006
1f4b88ab053d
Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents:
76841
diff
changeset
|
1180 @cindex modification time of file |
6555 | 1181 |
1182 @item | |
1183 The time of last status change as a list of two integers (as above). | |
1184 | |
1185 @item | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
1186 The size of the file in bytes. If the size is too large to fit in a |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
1187 Lisp integer, this is a floating point number. |
6555 | 1188 |
1189 @item | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1190 The file's modes, as a string of ten letters or dashes, |
6555 | 1191 as in @samp{ls -l}. |
1192 | |
1193 @item | |
52978
1a5c50faf357
Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents:
52401
diff
changeset
|
1194 @code{t} if the file's @acronym{GID} would change if file were |
6555 | 1195 deleted and recreated; @code{nil} otherwise. |
1196 | |
1197 @item | |
17919
eb712b69e495
The inode number can be an integer.
Richard M. Stallman <rms@gnu.org>
parents:
17398
diff
changeset
|
1198 The file's inode number. If possible, this is an integer. If the inode |
eb712b69e495
The inode number can be an integer.
Richard M. Stallman <rms@gnu.org>
parents:
17398
diff
changeset
|
1199 number is too large to be represented as an integer in Emacs Lisp, then |
eb712b69e495
The inode number can be an integer.
Richard M. Stallman <rms@gnu.org>
parents:
17398
diff
changeset
|
1200 the value has the form @code{(@var{high} . @var{low})}, where @var{low} |
eb712b69e495
The inode number can be an integer.
Richard M. Stallman <rms@gnu.org>
parents:
17398
diff
changeset
|
1201 holds the low 16 bits. |
6555 | 1202 |
1203 @item | |
39296
5f4f6cf4a868
(File Attributes): Document that the device number can also be a cons cell.
Eli Zaretskii <eliz@gnu.org>
parents:
37582
diff
changeset
|
1204 The file system number of the file system that the file is in. |
5f4f6cf4a868
(File Attributes): Document that the device number can also be a cons cell.
Eli Zaretskii <eliz@gnu.org>
parents:
37582
diff
changeset
|
1205 Depending on the magnitude of the value, this can be either an integer |
5f4f6cf4a868
(File Attributes): Document that the device number can also be a cons cell.
Eli Zaretskii <eliz@gnu.org>
parents:
37582
diff
changeset
|
1206 or a cons cell, in the same manner as the inode number. This element |
5f4f6cf4a868
(File Attributes): Document that the device number can also be a cons cell.
Eli Zaretskii <eliz@gnu.org>
parents:
37582
diff
changeset
|
1207 and the file's inode number together give enough information to |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
1208 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
|
1209 values for both of these numbers. |
6555 | 1210 @end enumerate |
1211 | |
1212 For example, here are the file attributes for @file{files.texi}: | |
1213 | |
1214 @example | |
1215 @group | |
53109
420dc7ac8867
(File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents:
52978
diff
changeset
|
1216 (file-attributes "files.texi" 'string) |
420dc7ac8867
(File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents:
52978
diff
changeset
|
1217 @result{} (nil 1 "lh" "users" |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
47980
diff
changeset
|
1218 (8489 20284) |
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
47980
diff
changeset
|
1219 (8489 20284) |
6555 | 1220 (8489 20285) |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
47980
diff
changeset
|
1221 14906 "-rw-rw-rw-" |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1222 nil 129500 -32252) |
6555 | 1223 @end group |
1224 @end example | |
1225 | |
1226 @noindent | |
1227 and here is how the result is interpreted: | |
1228 | |
1229 @table @code | |
1230 @item nil | |
1231 is neither a directory nor a symbolic link. | |
1232 | |
1233 @item 1 | |
1234 has only one name (the name @file{files.texi} in the current default | |
1235 directory). | |
1236 | |
53109
420dc7ac8867
(File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents:
52978
diff
changeset
|
1237 @item "lh" |
420dc7ac8867
(File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents:
52978
diff
changeset
|
1238 is owned by the user with name "lh". |
420dc7ac8867
(File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents:
52978
diff
changeset
|
1239 |
420dc7ac8867
(File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents:
52978
diff
changeset
|
1240 @item "users" |
420dc7ac8867
(File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents:
52978
diff
changeset
|
1241 is in the group with name "users". |
6555 | 1242 |
1243 @item (8489 20284) | |
12522 | 1244 was last accessed on Aug 19 00:09. |
6555 | 1245 |
1246 @item (8489 20284) | |
1247 was last modified on Aug 19 00:09. | |
1248 | |
1249 @item (8489 20285) | |
1250 last had its inode changed on Aug 19 00:09. | |
1251 | |
1252 @item 14906 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1253 is 14906 bytes long. (It may not contain 14906 characters, though, |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1254 if some of the bytes belong to multibyte sequences.) |
6555 | 1255 |
1256 @item "-rw-rw-rw-" | |
1257 has a mode of read and write access for the owner, group, and world. | |
1258 | |
1259 @item nil | |
52978
1a5c50faf357
Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents:
52401
diff
changeset
|
1260 would retain the same @acronym{GID} if it were recreated. |
6555 | 1261 |
1262 @item 129500 | |
1263 has an inode number of 129500. | |
1264 @item -32252 | |
1265 is on file system number -32252. | |
1266 @end table | |
1267 @end defun | |
1268 | |
62585
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1269 @node Locating Files |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1270 @subsection How to Locate Files in Standard Places |
77006
1f4b88ab053d
Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents:
76841
diff
changeset
|
1271 @cindex locate file in path |
1f4b88ab053d
Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents:
76841
diff
changeset
|
1272 @cindex find file in path |
62585
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1273 |
62856
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1274 This section explains how to search for a file in a list of |
77006
1f4b88ab053d
Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents:
76841
diff
changeset
|
1275 directories (a @dfn{path}). One example is when you need to look for |
1f4b88ab053d
Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents:
76841
diff
changeset
|
1276 a program's executable file, e.g., to find out whether a given program |
1f4b88ab053d
Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents:
76841
diff
changeset
|
1277 is installed on the user's system. Another example is the search for |
62585
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1278 Lisp libraries (@pxref{Library Search}). Such searches generally need |
62856
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1279 to try various possible file name extensions, in addition to various |
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1280 possible directories. Emacs provides a function for such a |
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1281 generalized search for a file. |
62585
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1282 |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1283 @defun locate-file filename path &optional suffixes predicate |
62856
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1284 This function searches for a file whose name is @var{filename} in a |
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1285 list of directories given by @var{path}, trying the suffixes in |
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1286 @var{suffixes}. If it finds such a file, it returns the full |
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1287 @dfn{absolute file name} of the file (@pxref{Relative File Names}); |
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1288 otherwise it returns @code{nil}. |
62585
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1289 |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1290 The optional argument @var{suffixes} gives the list of file-name |
62856
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1291 suffixes to append to @var{filename} when searching. |
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1292 @code{locate-file} tries each possible directory with each of these |
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1293 suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there |
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1294 are no suffixes, and @var{filename} is used only as-is. Typical |
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1295 values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess |
69201
0b687e350e7e
(Locating Files): Suggest additional values for the
Luc Teirlinck <teirllm@auburn.edu>
parents:
69015
diff
changeset
|
1296 Creation, exec-suffixes}), @code{load-suffixes}, |
0b687e350e7e
(Locating Files): Suggest additional values for the
Luc Teirlinck <teirllm@auburn.edu>
parents:
69015
diff
changeset
|
1297 @code{load-file-rep-suffixes} and the return value of the function |
0b687e350e7e
(Locating Files): Suggest additional values for the
Luc Teirlinck <teirllm@auburn.edu>
parents:
69015
diff
changeset
|
1298 @code{get-load-suffixes} (@pxref{Load Suffixes}). |
62856
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1299 |
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1300 Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess |
62585
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1301 Creation, exec-path}) when looking for executable programs or |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1302 @code{load-path} (@pxref{Library Search, load-path}) when looking for |
62856
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1303 Lisp files. If @var{filename} is absolute, @var{path} has no effect, |
19deaa395e85
(Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents:
62585
diff
changeset
|
1304 but the suffixes in @var{suffixes} are still tried. |
62585
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1305 |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1306 The optional argument @var{predicate}, if non-@code{nil}, specifies |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1307 the predicate function to use for testing whether a candidate file is |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1308 suitable. The predicate function is passed the candidate file name as |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1309 its single argument. If @var{predicate} is @code{nil} or unspecified, |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1310 @code{locate-file} uses @code{file-readable-p} as the default |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1311 predicate. Useful non-default predicates include |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1312 @code{file-executable-p}, @code{file-directory-p}, and other |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1313 predicates described in @ref{Kinds of Files}. |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1314 |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1315 For compatibility, @var{predicate} can also be one of the symbols |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1316 @code{executable}, @code{readable}, @code{writable}, @code{exists}, or |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1317 a list of one or more of these symbols. |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1318 @end defun |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1319 |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1320 @defun executable-find program |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1321 This function searches for the executable file of the named |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1322 @var{program} and returns the full absolute name of the executable, |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1323 including its file-name extensions, if any. It returns @code{nil} if |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1324 the file is not found. The functions searches in all the directories |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1325 in @code{exec-path} and tries all the file-name extensions in |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1326 @code{exec-suffixes}. |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1327 @end defun |
78962e585d20
(Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents:
61949
diff
changeset
|
1328 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1329 @node Changing Files |
6555 | 1330 @section Changing File Names and Attributes |
77006
1f4b88ab053d
Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents:
76841
diff
changeset
|
1331 @c @cindex renaming files Duplicates rename-file |
6555 | 1332 @cindex copying files |
1333 @cindex deleting files | |
1334 @cindex linking files | |
1335 @cindex setting modes of files | |
1336 | |
1337 The functions in this section rename, copy, delete, link, and set the | |
1338 modes of files. | |
1339 | |
1340 In the functions that have an argument @var{newname}, if a file by the | |
1341 name of @var{newname} already exists, the actions taken depend on the | |
1342 value of the argument @var{ok-if-already-exists}: | |
1343 | |
1344 @itemize @bullet | |
1345 @item | |
1346 Signal a @code{file-already-exists} error if | |
1347 @var{ok-if-already-exists} is @code{nil}. | |
1348 | |
1349 @item | |
1350 Request confirmation if @var{ok-if-already-exists} is a number. | |
1351 | |
1352 @item | |
1353 Replace the old file without confirmation if @var{ok-if-already-exists} | |
1354 is any other value. | |
1355 @end itemize | |
1356 | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1357 The next four commands all recursively follow symbolic links at all |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1358 levels of parent directories for their first argument, but, if that |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1359 argument is itself a symbolic link, then only @code{copy-file} |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1360 replaces it with its (recursive) target. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1361 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1362 @deffn Command add-name-to-file oldname newname &optional ok-if-already-exists |
6555 | 1363 @cindex file with multiple names |
1364 @cindex file hard link | |
1365 This function gives the file named @var{oldname} the additional name | |
1366 @var{newname}. This means that @var{newname} becomes a new ``hard | |
1367 link'' to @var{oldname}. | |
1368 | |
1369 In the first part of the following example, we list two files, | |
1370 @file{foo} and @file{foo3}. | |
1371 | |
1372 @example | |
1373 @group | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1374 % ls -li fo* |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1375 81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1376 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 |
6555 | 1377 @end group |
1378 @end example | |
1379 | |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
1380 Now we create a hard link, by calling @code{add-name-to-file}, then list |
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
1381 the files again. This shows two names for one file, @file{foo} and |
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
1382 @file{foo2}. |
6555 | 1383 |
1384 @example | |
1385 @group | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1386 (add-name-to-file "foo" "foo2") |
6555 | 1387 @result{} nil |
1388 @end group | |
1389 | |
1390 @group | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1391 % ls -li fo* |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1392 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1393 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1394 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 |
6555 | 1395 @end group |
1396 @end example | |
1397 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1398 Finally, we evaluate the following: |
6555 | 1399 |
1400 @example | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1401 (add-name-to-file "foo" "foo3" t) |
6555 | 1402 @end example |
1403 | |
1404 @noindent | |
1405 and list the files again. Now there are three names | |
1406 for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old | |
1407 contents of @file{foo3} are lost. | |
1408 | |
1409 @example | |
1410 @group | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1411 (add-name-to-file "foo1" "foo3") |
6555 | 1412 @result{} nil |
1413 @end group | |
1414 | |
1415 @group | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1416 % ls -li fo* |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1417 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1418 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1419 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3 |
6555 | 1420 @end group |
1421 @end example | |
1422 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1423 This function is meaningless on operating systems where multiple names |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1424 for one file are not allowed. Some systems implement multiple names |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1425 by copying the file instead. |
6555 | 1426 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1427 See also @code{file-nlinks} in @ref{File Attributes}. |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1428 @end deffn |
6555 | 1429 |
1430 @deffn Command rename-file filename newname &optional ok-if-already-exists | |
1431 This command renames the file @var{filename} as @var{newname}. | |
1432 | |
1433 If @var{filename} has additional names aside from @var{filename}, it | |
1434 continues to have those names. In fact, adding the name @var{newname} | |
1435 with @code{add-name-to-file} and then deleting @var{filename} has the | |
1436 same effect as renaming, aside from momentary intermediate states. | |
1437 @end deffn | |
1438 | |
71003
7733ed75db62
* files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents:
70657
diff
changeset
|
1439 @deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid |
6555 | 1440 This command copies the file @var{oldname} to @var{newname}. An |
51913
3abc365e9d90
(Changing Files): copy-file allows dir as NEWNAME.
Richard M. Stallman <rms@gnu.org>
parents:
51793
diff
changeset
|
1441 error is signaled if @var{oldname} does not exist. If @var{newname} |
3abc365e9d90
(Changing Files): copy-file allows dir as NEWNAME.
Richard M. Stallman <rms@gnu.org>
parents:
51793
diff
changeset
|
1442 names a directory, it copies @var{oldname} into that directory, |
3abc365e9d90
(Changing Files): copy-file allows dir as NEWNAME.
Richard M. Stallman <rms@gnu.org>
parents:
51793
diff
changeset
|
1443 preserving its final name component. |
6555 | 1444 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1445 If @var{time} is non-@code{nil}, then this function gives the new file |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1446 the same last-modified time that the old one has. (This works on only |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1447 some operating systems.) If setting the time gets an error, |
71003
7733ed75db62
* files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents:
70657
diff
changeset
|
1448 @code{copy-file} signals a @code{file-date-error} error. In an |
7733ed75db62
* files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents:
70657
diff
changeset
|
1449 interactive call, a prefix argument specifies a non-@code{nil} value |
7733ed75db62
* files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents:
70657
diff
changeset
|
1450 for @var{time}. |
6555 | 1451 |
51558
5a85c7c1d3ab
(Changing Files): copy-file copies file modes, too.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
51020
diff
changeset
|
1452 This function copies the file modes, too. |
5a85c7c1d3ab
(Changing Files): copy-file copies file modes, too.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
51020
diff
changeset
|
1453 |
71003
7733ed75db62
* files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents:
70657
diff
changeset
|
1454 If argument @var{preserve-uid-gid} is @code{nil}, we let the operating |
7733ed75db62
* files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents:
70657
diff
changeset
|
1455 system decide the user and group ownership of the new file (this is |
7733ed75db62
* files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents:
70657
diff
changeset
|
1456 usually set to the user running Emacs). If @var{preserve-uid-gid} is |
7733ed75db62
* files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents:
70657
diff
changeset
|
1457 non-@code{nil}, we attempt to copy the user and group ownership of the |
7733ed75db62
* files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents:
70657
diff
changeset
|
1458 file. This works only on some operating systems, and only if you have |
7733ed75db62
* files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents:
70657
diff
changeset
|
1459 the correct permissions to do so. |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1460 @end deffn |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1461 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1462 @deffn Command make-symbolic-link filename newname &optional ok-if-exists |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1463 @pindex ln |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1464 @kindex file-already-exists |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1465 This command makes a symbolic link to @var{filename}, named |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1466 @var{newname}. This is like the shell command @samp{ln -s |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1467 @var{filename} @var{newname}}. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1468 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1469 This function is not available on systems that don't support symbolic |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1470 links. |
6555 | 1471 @end deffn |
1472 | |
1473 @deffn Command delete-file filename | |
1474 @pindex rm | |
1475 This command deletes the file @var{filename}, like the shell command | |
1476 @samp{rm @var{filename}}. If the file has multiple names, it continues | |
1477 to exist under the other names. | |
1478 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1479 A suitable kind of @code{file-error} error is signaled if the file does |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1480 not exist, or is not deletable. (On Unix and GNU/Linux, a file is |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1481 deletable if its directory is writable.) |
6555 | 1482 |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1483 If @var{filename} is a symbolic link, @code{delete-file} does not |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1484 replace it with its target, but it does follow symbolic links at all |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1485 levels of parent directories. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1486 |
6555 | 1487 See also @code{delete-directory} in @ref{Create/Delete Dirs}. |
1488 @end deffn | |
1489 | |
1490 @defun define-logical-name varname string | |
54025
8659505a7f3d
(Changing Files): Fix argname.
Richard M. Stallman <rms@gnu.org>
parents:
53575
diff
changeset
|
1491 This function defines the logical name @var{varname} to have the value |
6555 | 1492 @var{string}. It is available only on VMS. |
1493 @end defun | |
1494 | |
1495 @defun set-file-modes filename mode | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1496 This function sets mode bits of @var{filename} to @var{mode} (which |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1497 must be an integer). Only the low 12 bits of @var{mode} are used. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1498 This function recursively follows symbolic links at all levels for |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1499 @var{filename}. |
6555 | 1500 @end defun |
1501 | |
1502 @c Emacs 19 feature | |
1503 @defun set-default-file-modes mode | |
47514
e0d6f0b369d1
Add `umask' to the concept index.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
46956
diff
changeset
|
1504 @cindex umask |
6555 | 1505 This function sets the default file protection for new files created by |
1506 Emacs and its subprocesses. Every file created with Emacs initially has | |
28074
25557ce6a3a0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
1507 this protection, or a subset of it (@code{write-region} will not give a |
25557ce6a3a0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
1508 file execute permission even if the default file protection allows |
25557ce6a3a0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
1509 execute permission). On Unix and GNU/Linux, the default protection is |
25557ce6a3a0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
1510 the bitwise complement of the ``umask'' value. |
6555 | 1511 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1512 The argument @var{mode} must be an integer. On most systems, only the |
28074
25557ce6a3a0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
1513 low 9 bits of @var{mode} are meaningful. You can use the Lisp construct |
25557ce6a3a0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
1514 for octal character codes to enter @var{mode}; for example, |
25557ce6a3a0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
1515 |
25557ce6a3a0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
1516 @example |
25557ce6a3a0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
1517 (set-default-file-modes ?\644) |
25557ce6a3a0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
1518 @end example |
6555 | 1519 |
1520 Saving a modified version of an existing file does not count as creating | |
28074
25557ce6a3a0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
1521 the file; it preserves the existing file's mode, whatever that is. So |
25557ce6a3a0
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27259
diff
changeset
|
1522 the default file protection has no effect. |
6555 | 1523 @end defun |
1524 | |
1525 @defun default-file-modes | |
1526 This function returns the current default protection value. | |
1527 @end defun | |
1528 | |
55192
dd5538a91d27
(Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents:
54861
diff
changeset
|
1529 @defun set-file-times filename &optional time |
dd5538a91d27
(Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents:
54861
diff
changeset
|
1530 This function sets the access and modification times of @var{filename} |
dd5538a91d27
(Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents:
54861
diff
changeset
|
1531 to @var{time}. The return value is @code{t} if the times are successfully |
dd5538a91d27
(Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents:
54861
diff
changeset
|
1532 set, otherwise it is @code{nil}. @var{time} defaults to the current |
dd5538a91d27
(Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents:
54861
diff
changeset
|
1533 time and must be in the format returned by @code{current-time} |
dd5538a91d27
(Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents:
54861
diff
changeset
|
1534 (@pxref{Time of Day}). |
dd5538a91d27
(Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents:
54861
diff
changeset
|
1535 @end defun |
dd5538a91d27
(Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents:
54861
diff
changeset
|
1536 |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1537 @cindex MS-DOS and file modes |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1538 @cindex file modes and MS-DOS |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1539 On MS-DOS, there is no such thing as an ``executable'' file mode bit. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1540 So Emacs considers a file executable if its name ends in one of the |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1541 standard executable extensions, such as @file{.com}, @file{.bat}, |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1542 @file{.exe}, and some others. Files that begin with the Unix-standard |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1543 @samp{#!} signature, such as shell and Perl scripts, are also considered |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1544 as executable files. This is reflected in the values returned by |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1545 @code{file-modes} and @code{file-attributes}. Directories are also |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1546 reported with executable bit set, for compatibility with Unix. |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1547 |
6555 | 1548 @node File Names |
1549 @section File Names | |
1550 @cindex file names | |
1551 | |
1552 Files are generally referred to by their names, in Emacs as elsewhere. | |
1553 File names in Emacs are represented as strings. The functions that | |
1554 operate on a file all expect a file name argument. | |
1555 | |
1556 In addition to operating on files themselves, Emacs Lisp programs | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1557 often need to operate on file names; i.e., to take them apart and to use |
6555 | 1558 part of a name to construct related file names. This section describes |
1559 how to manipulate file names. | |
1560 | |
1561 The functions in this section do not actually access files, so they | |
1562 can operate on file names that do not refer to an existing file or | |
1563 directory. | |
1564 | |
28635
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1565 On MS-DOS and MS-Windows, these functions (like the function that |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1566 actually operate on files) accept MS-DOS or MS-Windows file-name syntax, |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1567 where backslashes separate the components, as well as Unix syntax; but |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1568 they always return Unix syntax. On VMS, these functions (and the ones |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1569 that operate on files) understand both VMS file-name syntax and Unix |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1570 syntax. This enables Lisp programs to specify file names in Unix syntax |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1571 and work properly on all systems without change. |
6555 | 1572 |
1573 @menu | |
1574 * File Name Components:: The directory part of a file name, and the rest. | |
46956
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1575 * Relative File Names:: Some file names are relative to a current directory. |
6555 | 1576 * Directory Names:: A directory's name as a directory |
1577 is different from its name as a file. | |
1578 * File Name Expansion:: Converting relative file names to absolute ones. | |
1579 * Unique File Names:: Generating names for temporary files. | |
1580 * File Name Completion:: Finding the completions for a given file name. | |
15765
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1581 * Standard File Names:: If your package uses a fixed file name, |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
1582 how to handle various operating systems simply. |
6555 | 1583 @end menu |
1584 | |
1585 @node File Name Components | |
1586 @subsection File Name Components | |
1587 @cindex directory part (of file name) | |
1588 @cindex nondirectory part (of file name) | |
1589 @cindex version number (in file name) | |
1590 | |
1591 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
|
1592 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
|
1593 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
|
1594 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
|
1595 (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
|
1596 Concatenating these two parts reproduces the original file name. |
6555 | 1597 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1598 On most systems, the directory part is everything up to and including |
28635
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1599 the last slash (backslash is also allowed in input on MS-DOS or |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1600 MS-Windows); the nondirectory part is the rest. The rules in VMS syntax |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1601 are complicated. |
6555 | 1602 |
1603 For some purposes, the nondirectory part is further subdivided into | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1604 the name proper and the @dfn{version number}. On most systems, only |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1605 backup files have version numbers in their names. On VMS, every file |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1606 has a version number, but most of the time the file name actually used |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1607 in Emacs omits the version number, so that version numbers in Emacs are |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1608 found mostly in directory lists. |
6555 | 1609 |
1610 @defun file-name-directory filename | |
46956
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1611 This function returns the directory part of @var{filename}, as a |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1612 directory name (@pxref{Directory Names}), or @code{nil} if |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1613 @var{filename} does not include a directory part. |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1614 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1615 On GNU and Unix systems, a string returned by this function always |
70538 | 1616 ends in a slash. On MS-DOS it can also end in a colon. On VMS, it |
46956
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1617 returns a string ending in one of the three characters @samp{:}, |
6555 | 1618 @samp{]}, or @samp{>}. |
1619 | |
1620 @example | |
1621 @group | |
1622 (file-name-directory "lewis/foo") ; @r{Unix example} | |
1623 @result{} "lewis/" | |
1624 @end group | |
1625 @group | |
1626 (file-name-directory "foo") ; @r{Unix example} | |
1627 @result{} nil | |
1628 @end group | |
1629 @group | |
1630 (file-name-directory "[X]FOO.TMP") ; @r{VMS example} | |
1631 @result{} "[X]" | |
1632 @end group | |
1633 @end example | |
1634 @end defun | |
1635 | |
1636 @defun file-name-nondirectory filename | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1637 This function returns the nondirectory part of @var{filename}. |
6555 | 1638 |
1639 @example | |
1640 @group | |
1641 (file-name-nondirectory "lewis/foo") | |
1642 @result{} "foo" | |
1643 @end group | |
1644 @group | |
1645 (file-name-nondirectory "foo") | |
1646 @result{} "foo" | |
1647 @end group | |
1648 @group | |
46956
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1649 (file-name-nondirectory "lewis/") |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1650 @result{} "" |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1651 @end group |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1652 @group |
6555 | 1653 ;; @r{The following example is accurate only on VMS.} |
1654 (file-name-nondirectory "[X]FOO.TMP") | |
1655 @result{} "FOO.TMP" | |
1656 @end group | |
1657 @end example | |
1658 @end defun | |
1659 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1660 @defun file-name-sans-versions filename &optional keep-backup-version |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1661 This function returns @var{filename} with any file version numbers, |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1662 backup version numbers, or trailing tildes discarded. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1663 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1664 If @var{keep-backup-version} is non-@code{nil}, then true file version |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1665 numbers understood as such by the file system are discarded from the |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1666 return value, but backup version numbers are kept. |
6555 | 1667 |
1668 @example | |
1669 @group | |
1670 (file-name-sans-versions "~rms/foo.~1~") | |
1671 @result{} "~rms/foo" | |
1672 @end group | |
1673 @group | |
1674 (file-name-sans-versions "~rms/foo~") | |
1675 @result{} "~rms/foo" | |
1676 @end group | |
1677 @group | |
1678 (file-name-sans-versions "~rms/foo") | |
1679 @result{} "~rms/foo" | |
1680 @end group | |
1681 @group | |
1682 ;; @r{The following example applies to VMS only.} | |
1683 (file-name-sans-versions "foo;23") | |
1684 @result{} "foo" | |
1685 @end group | |
1686 @end example | |
1687 @end defun | |
1688 | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1689 @defun file-name-extension filename &optional period |
71957
61cb5aae3bc3
Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents:
71709
diff
changeset
|
1690 This function returns @var{filename}'s final ``extension,'' if any, |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1691 after applying @code{file-name-sans-versions} to remove any |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1692 version/backup part. The extension, in a file name, is the part that |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1693 starts with the last @samp{.} in the last name component (minus |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1694 any version/backup part). |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1695 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1696 This function returns @code{nil} for extensionless file names such as |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1697 @file{foo}. It returns @code{""} for null extensions, as in |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1698 @file{foo.}. If the last component of a file name begins with a |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1699 @samp{.}, that @samp{.} doesn't count as the beginning of an |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1700 extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1701 @samp{.emacs}. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1702 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1703 If @var{period} is non-@code{nil}, then the returned value includes |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1704 the period that delimits the extension, and if @var{filename} has no |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1705 extension, the value is @code{""}. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1706 @end defun |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1707 |
12067 | 1708 @defun file-name-sans-extension filename |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1709 This function returns @var{filename} minus its extension, if any. The |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1710 version/backup part, if present, is only removed if the file has an |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1711 extension. For example, |
12098 | 1712 |
1713 @example | |
1714 (file-name-sans-extension "foo.lose.c") | |
1715 @result{} "foo.lose" | |
1716 (file-name-sans-extension "big.hack/foo") | |
1717 @result{} "big.hack/foo" | |
40188
cd1cd95ca64e
(File Name Components): Update the description of
Eli Zaretskii <eliz@gnu.org>
parents:
39883
diff
changeset
|
1718 (file-name-sans-extension "/my/home/.emacs") |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
1719 @result{} "/my/home/.emacs" |
40188
cd1cd95ca64e
(File Name Components): Update the description of
Eli Zaretskii <eliz@gnu.org>
parents:
39883
diff
changeset
|
1720 (file-name-sans-extension "/my/home/.emacs.el") |
cd1cd95ca64e
(File Name Components): Update the description of
Eli Zaretskii <eliz@gnu.org>
parents:
39883
diff
changeset
|
1721 @result{} "/my/home/.emacs" |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1722 (file-name-sans-extension "~/foo.el.~3~") |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1723 @result{} "~/foo" |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1724 (file-name-sans-extension "~/foo.~3~") |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1725 @result{} "~/foo.~3~" |
12098 | 1726 @end example |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1727 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1728 Note that the @samp{.~3~} in the two last examples is the backup part, |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1729 not an extension. |
12067 | 1730 @end defun |
1731 | |
28635
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1732 @ignore |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
47980
diff
changeset
|
1733 Andrew Innes says that this |
28635
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1734 |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1735 @c @defvar directory-sep-char |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1736 This variable holds the character that Emacs normally uses to separate |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1737 file name components. The default value is @code{?/}, but on MS-Windows |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1738 you can set it to @code{?\\}; then the functions that transform file names |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1739 use backslashes in their output. |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1740 |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1741 File names using backslashes work as input to Lisp primitives even on |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1742 MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1743 value of @code{?/}. |
28608
c46c2efa3731
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28074
diff
changeset
|
1744 @end defvar |
28635
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
1745 @end ignore |
28608
c46c2efa3731
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28074
diff
changeset
|
1746 |
6555 | 1747 @node Relative File Names |
1748 @subsection Absolute and Relative File Names | |
1749 @cindex absolute file name | |
1750 @cindex relative file name | |
1751 | |
1752 All the directories in the file system form a tree starting at the | |
1753 root directory. A file name can specify all the directory names | |
1754 starting from the root of the tree; then it is called an @dfn{absolute} | |
1755 file name. Or it can specify the position of the file in the tree | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1756 relative to a default directory; then it is called a @dfn{relative} file |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1757 name. On Unix and GNU/Linux, an absolute file name starts with a slash |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1758 or a tilde (@samp{~}), and a relative one does not. On MS-DOS and |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1759 MS-Windows, an absolute file name starts with a slash or a backslash, or |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
1760 with a drive specification @samp{@var{x}:/}, where @var{x} is the |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
1761 @dfn{drive letter}. The rules on VMS are complicated. |
6555 | 1762 |
1763 @defun file-name-absolute-p filename | |
1764 This function returns @code{t} if file @var{filename} is an absolute | |
1765 file name, @code{nil} otherwise. On VMS, this function understands both | |
1766 Unix syntax and VMS syntax. | |
1767 | |
1768 @example | |
1769 @group | |
1770 (file-name-absolute-p "~rms/foo") | |
1771 @result{} t | |
1772 @end group | |
1773 @group | |
1774 (file-name-absolute-p "rms/foo") | |
1775 @result{} nil | |
1776 @end group | |
1777 @group | |
1778 (file-name-absolute-p "/user/rms/foo") | |
1779 @result{} t | |
1780 @end group | |
1781 @end example | |
1782 @end defun | |
1783 | |
69015
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1784 Given a possibly relative file name, you can convert it to an |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1785 absolute name using @code{expand-file-name} (@pxref{File Name |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1786 Expansion}). This function converts absolute file names to relative |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1787 names: |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1788 |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1789 @defun file-relative-name filename &optional directory |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1790 This function tries to return a relative name that is equivalent to |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1791 @var{filename}, assuming the result will be interpreted relative to |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1792 @var{directory} (an absolute directory name or directory file name). |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1793 If @var{directory} is omitted or @code{nil}, it defaults to the |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1794 current buffer's default directory. |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1795 |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1796 On some operating systems, an absolute file name begins with a device |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1797 name. On such systems, @var{filename} has no relative equivalent based |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1798 on @var{directory} if they start with two different device names. In |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1799 this case, @code{file-relative-name} returns @var{filename} in absolute |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1800 form. |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1801 |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1802 @example |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1803 (file-relative-name "/foo/bar" "/foo/") |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1804 @result{} "bar" |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1805 (file-relative-name "/foo/bar" "/hack/") |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1806 @result{} "../foo/bar" |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1807 @end example |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1808 @end defun |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1809 |
46956
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1810 @node Directory Names |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1811 @comment node-name, next, previous, up |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1812 @subsection Directory Names |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1813 @cindex directory name |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1814 @cindex file name of directory |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1815 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1816 A @dfn{directory name} is the name of a directory. A directory is |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1817 actually a kind of file, so it has a file name, which is related to |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1818 the directory name but not identical to it. (This is not quite the |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1819 same as the usual Unix terminology.) These two different names for |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1820 the same entity are related by a syntactic transformation. On GNU and |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1821 Unix systems, this is simple: a directory name ends in a slash, |
70538 | 1822 whereas the directory's name as a file lacks that slash. On MS-DOS and |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1823 VMS, the relationship is more complicated. |
46956
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1824 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1825 The difference between a directory name and its name as a file is |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1826 subtle but crucial. When an Emacs variable or function argument is |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1827 described as being a directory name, a file name of a directory is not |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1828 acceptable. When @code{file-name-directory} returns a string, that is |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1829 always a directory name. |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1830 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1831 The following two functions convert between directory names and file |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1832 names. They do nothing special with environment variable substitutions |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1833 such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}. |
46956
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1834 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1835 @defun file-name-as-directory filename |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1836 This function returns a string representing @var{filename} in a form |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1837 that the operating system will interpret as the name of a directory. On |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1838 most systems, this means appending a slash to the string (if it does not |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1839 already end in one). On VMS, the function converts a string of the form |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1840 @file{[X]Y.DIR.1} to the form @file{[X.Y]}. |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1841 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1842 @example |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1843 @group |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1844 (file-name-as-directory "~rms/lewis") |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1845 @result{} "~rms/lewis/" |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1846 @end group |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1847 @end example |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1848 @end defun |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1849 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1850 @defun directory-file-name dirname |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1851 This function returns a string representing @var{dirname} in a form that |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1852 the operating system will interpret as the name of a file. On most |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1853 systems, this means removing the final slash (or backslash) from the |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1854 string. On VMS, the function converts a string of the form @file{[X.Y]} |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1855 to @file{[X]Y.DIR.1}. |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1856 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1857 @example |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1858 @group |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1859 (directory-file-name "~lewis/") |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1860 @result{} "~lewis" |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1861 @end group |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1862 @end example |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1863 @end defun |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1864 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1865 Given a directory name, you can combine it with a relative file name |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1866 using @code{concat}: |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1867 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1868 @example |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1869 (concat @var{dirname} @var{relfile}) |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1870 @end example |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1871 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1872 @noindent |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1873 Be sure to verify that the file name is relative before doing that. |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1874 If you use an absolute file name, the results could be syntactically |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1875 invalid or refer to the wrong file. |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1876 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1877 If you want to use a directory file name in making such a |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1878 combination, you must first convert it to a directory name using |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1879 @code{file-name-as-directory}: |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1880 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1881 @example |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1882 (concat (file-name-as-directory @var{dirfile}) @var{relfile}) |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1883 @end example |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1884 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1885 @noindent |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1886 Don't try concatenating a slash by hand, as in |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1887 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1888 @example |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1889 ;;; @r{Wrong!} |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1890 (concat @var{dirfile} "/" @var{relfile}) |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1891 @end example |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1892 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1893 @noindent |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1894 because this is not portable. Always use |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1895 @code{file-name-as-directory}. |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1896 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1897 @cindex directory name abbreviation |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1898 Directory name abbreviations are useful for directories that are |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1899 normally accessed through symbolic links. Sometimes the users recognize |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1900 primarily the link's name as ``the name'' of the directory, and find it |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1901 annoying to see the directory's ``real'' name. If you define the link |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1902 name as an abbreviation for the ``real'' name, Emacs shows users the |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1903 abbreviation instead. |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1904 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1905 @defvar directory-abbrev-alist |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1906 The variable @code{directory-abbrev-alist} contains an alist of |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1907 abbreviations to use for file directories. Each element has the form |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1908 @code{(@var{from} . @var{to})}, and says to replace @var{from} with |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1909 @var{to} when it appears in a directory name. The @var{from} string is |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1910 actually a regular expression; it should always start with @samp{^}. |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1911 The @var{to} string should be an ordinary absolute directory name. Do |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1912 not use @samp{~} to stand for a home directory in that string. The |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1913 function @code{abbreviate-file-name} performs these substitutions. |
46956
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1914 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1915 You can set this variable in @file{site-init.el} to describe the |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1916 abbreviations appropriate for your site. |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1917 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1918 Here's an example, from a system on which file system @file{/home/fsf} |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1919 and so on are normally accessed through symbolic links named @file{/fsf} |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1920 and so on. |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1921 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1922 @example |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1923 (("^/home/fsf" . "/fsf") |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1924 ("^/home/gp" . "/gp") |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1925 ("^/home/gd" . "/gd")) |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1926 @end example |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1927 @end defvar |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1928 |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1929 To convert a directory name to its abbreviation, use this |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1930 function: |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1931 |
56215 | 1932 @defun abbreviate-file-name filename |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1933 @anchor{Definition of abbreviate-file-name} |
46956
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1934 This function applies abbreviations from @code{directory-abbrev-alist} |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1935 to its argument, and substitutes @samp{~} for the user's home |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1936 directory. You can use it for directory names and for file names, |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1937 because it recognizes abbreviations even as part of the name. |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1938 @end defun |
2c01ee3e5305
Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents:
45979
diff
changeset
|
1939 |
6555 | 1940 @node File Name Expansion |
1941 @subsection Functions that Expand Filenames | |
1942 @cindex expansion of file names | |
1943 | |
1944 @dfn{Expansion} of a file name means converting a relative file name | |
1945 to an absolute one. Since this is done relative to a default directory, | |
1946 you must specify the default directory name as well as the file name to | |
1947 be expanded. Expansion also simplifies file names by eliminating | |
1948 redundancies such as @file{./} and @file{@var{name}/../}. | |
1949 | |
1950 @defun expand-file-name filename &optional directory | |
1951 This function converts @var{filename} to an absolute file name. If | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1952 @var{directory} is supplied, it is the default directory to start with |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
1953 if @var{filename} is relative. (The value of @var{directory} should |
69015
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1954 itself be an absolute directory name or directory file name; it may |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1955 start with @samp{~}.) Otherwise, the current buffer's value of |
761f4a4fe6e8
(Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents:
68648
diff
changeset
|
1956 @code{default-directory} is used. For example: |
6555 | 1957 |
1958 @example | |
1959 @group | |
1960 (expand-file-name "foo") | |
1961 @result{} "/xcssun/users/rms/lewis/foo" | |
1962 @end group | |
1963 @group | |
1964 (expand-file-name "../foo") | |
1965 @result{} "/xcssun/users/rms/foo" | |
1966 @end group | |
1967 @group | |
1968 (expand-file-name "foo" "/usr/spool/") | |
1969 @result{} "/usr/spool/foo" | |
1970 @end group | |
1971 @group | |
1972 (expand-file-name "$HOME/foo") | |
1973 @result{} "/xcssun/users/rms/lewis/$HOME/foo" | |
1974 @end group | |
1975 @end example | |
1976 | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1977 If the part of the combined file name before the first slash is |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1978 @samp{~}, it expands to the value of the @env{HOME} environment |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1979 variable (usually your home directory). If the part before the first |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1980 slash is @samp{~@var{user}} and if @var{user} is a valid login name, |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1981 it expands to @var{user}'s home directory. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
1982 |
6555 | 1983 Filenames containing @samp{.} or @samp{..} are simplified to their |
1984 canonical form: | |
1985 | |
1986 @example | |
1987 @group | |
1988 (expand-file-name "bar/../foo") | |
1989 @result{} "/xcssun/users/rms/lewis/foo" | |
1990 @end group | |
1991 @end example | |
1992 | |
77361
916f8aa2138d
(File Name Expansion): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents:
77302
diff
changeset
|
1993 In some cases, a leading @samp{..} component can remain in the output: |
77302
95a196e2e465
(File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents:
77006
diff
changeset
|
1994 |
95a196e2e465
(File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents:
77006
diff
changeset
|
1995 @example |
95a196e2e465
(File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents:
77006
diff
changeset
|
1996 @group |
95a196e2e465
(File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents:
77006
diff
changeset
|
1997 (expand-file-name "../home" "/") |
95a196e2e465
(File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents:
77006
diff
changeset
|
1998 @result{} "/../home" |
95a196e2e465
(File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents:
77006
diff
changeset
|
1999 @end group |
95a196e2e465
(File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents:
77006
diff
changeset
|
2000 @end example |
95a196e2e465
(File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents:
77006
diff
changeset
|
2001 |
77361
916f8aa2138d
(File Name Expansion): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents:
77302
diff
changeset
|
2002 @noindent |
916f8aa2138d
(File Name Expansion): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents:
77302
diff
changeset
|
2003 This is for the sake of filesystems that have the concept of a |
77302
95a196e2e465
(File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents:
77006
diff
changeset
|
2004 ``superroot'' above the root directory @file{/}. On other filesystems, |
95a196e2e465
(File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents:
77006
diff
changeset
|
2005 @file{/../} is interpreted exactly the same as @file{/}. |
95a196e2e465
(File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents:
77006
diff
changeset
|
2006 |
6555 | 2007 Note that @code{expand-file-name} does @emph{not} expand environment |
2008 variables; only @code{substitute-in-file-name} does that. | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2009 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2010 Note also that @code{expand-file-name} does not follow symbolic links |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2011 at any level. This results in a difference between the way |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2012 @code{file-truename} and @code{expand-file-name} treat @samp{..}. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2013 Assuming that @samp{/tmp/bar} is a symbolic link to the directory |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2014 @samp{/tmp/foo/bar} we get: |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2015 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2016 @example |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2017 @group |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2018 (file-truename "/tmp/bar/../myfile") |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2019 @result{} "/tmp/foo/myfile" |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2020 @end group |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2021 @group |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2022 (expand-file-name "/tmp/bar/../myfile") |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2023 @result{} "/tmp/myfile" |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2024 @end group |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2025 @end example |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2026 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2027 If you may need to follow symbolic links preceding @samp{..}, you |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2028 should make sure to call @code{file-truename} without prior direct or |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2029 indirect calls to @code{expand-file-name}. @xref{Truenames}. |
6555 | 2030 @end defun |
2031 | |
2032 @defvar default-directory | |
2033 The value of this buffer-local variable is the default directory for the | |
2034 current buffer. It should be an absolute directory name; it may start | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2035 with @samp{~}. This variable is buffer-local in every buffer. |
6555 | 2036 |
2037 @code{expand-file-name} uses the default directory when its second | |
2038 argument is @code{nil}. | |
2039 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2040 Aside from VMS, the value is always a string ending with a slash. |
6555 | 2041 |
2042 @example | |
2043 @group | |
2044 default-directory | |
2045 @result{} "/user/lewis/manual/" | |
2046 @end group | |
2047 @end example | |
2048 @end defvar | |
2049 | |
56215 | 2050 @defun substitute-in-file-name filename |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2051 @anchor{Definition of substitute-in-file-name} |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2052 This function replaces environment variable references in |
51793
ccbf5ac3316d
(File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents:
51654
diff
changeset
|
2053 @var{filename} with the environment variable values. Following |
ccbf5ac3316d
(File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents:
51654
diff
changeset
|
2054 standard Unix shell syntax, @samp{$} is the prefix to substitute an |
ccbf5ac3316d
(File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents:
51654
diff
changeset
|
2055 environment variable value. If the input contains @samp{$$}, that is |
ccbf5ac3316d
(File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents:
51654
diff
changeset
|
2056 converted to @samp{$}; this gives the user a way to ``quote'' a |
ccbf5ac3316d
(File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents:
51654
diff
changeset
|
2057 @samp{$}. |
6555 | 2058 |
2059 The environment variable name is the series of alphanumeric characters | |
2060 (including underscores) that follow the @samp{$}. If the character following | |
2061 the @samp{$} is a @samp{@{}, then the variable name is everything up to the | |
2062 matching @samp{@}}. | |
2063 | |
51793
ccbf5ac3316d
(File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents:
51654
diff
changeset
|
2064 Calling @code{substitute-in-file-name} on output produced by |
ccbf5ac3316d
(File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents:
51654
diff
changeset
|
2065 @code{substitute-in-file-name} tends to give incorrect results. For |
ccbf5ac3316d
(File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents:
51654
diff
changeset
|
2066 instance, use of @samp{$$} to quote a single @samp{$} won't work |
ccbf5ac3316d
(File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents:
51654
diff
changeset
|
2067 properly, and @samp{$} in an environment variable's value could lead |
ccbf5ac3316d
(File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents:
51654
diff
changeset
|
2068 to repeated substitution. Therefore, programs that call this function |
ccbf5ac3316d
(File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents:
51654
diff
changeset
|
2069 and put the output where it will be passed to this function need to |
ccbf5ac3316d
(File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents:
51654
diff
changeset
|
2070 double all @samp{$} characters to prevent subsequent incorrect |
ccbf5ac3316d
(File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents:
51654
diff
changeset
|
2071 results. |
ccbf5ac3316d
(File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents:
51654
diff
changeset
|
2072 |
6555 | 2073 @c Wordy to avoid overfull hbox. --rjc 15mar92 |
2074 Here we assume that the environment variable @code{HOME}, which holds | |
2075 the user's home directory name, has value @samp{/xcssun/users/rms}. | |
2076 | |
2077 @example | |
2078 @group | |
2079 (substitute-in-file-name "$HOME/foo") | |
2080 @result{} "/xcssun/users/rms/foo" | |
2081 @end group | |
2082 @end example | |
2083 | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2084 After substitution, if a @samp{~} or a @samp{/} appears immediately |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2085 after another @samp{/}, the function discards everything before it (up |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2086 through the immediately preceding @samp{/}). |
6555 | 2087 |
2088 @example | |
2089 @group | |
2090 (substitute-in-file-name "bar/~/foo") | |
2091 @result{} "~/foo" | |
2092 @end group | |
2093 @group | |
2094 (substitute-in-file-name "/usr/local/$HOME/foo") | |
2095 @result{} "/xcssun/users/rms/foo" | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2096 ;; @r{@file{/usr/local/} has been discarded.} |
6555 | 2097 @end group |
2098 @end example | |
2099 | |
2100 On VMS, @samp{$} substitution is not done, so this function does nothing | |
2101 on VMS except discard superfluous initial components as shown above. | |
2102 @end defun | |
2103 | |
2104 @node Unique File Names | |
2105 @subsection Generating Unique File Names | |
2106 | |
2107 Some programs need to write temporary files. Here is the usual way to | |
60444
78a2cd972ba1
(Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents:
59877
diff
changeset
|
2108 construct a name for such a file: |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2109 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2110 @example |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2111 (make-temp-file @var{name-of-application}) |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2112 @end example |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2113 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2114 @noindent |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2115 The job of @code{make-temp-file} is to prevent two different users or |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2116 two different jobs from trying to use the exact same file name. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2117 |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2118 @defun make-temp-file prefix &optional dir-flag suffix |
61795
8757023049af
(Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents:
61793
diff
changeset
|
2119 This function creates a temporary file and returns its name. Emacs |
8757023049af
(Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents:
61793
diff
changeset
|
2120 creates the temporary file's name by adding to @var{prefix} some |
8757023049af
(Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents:
61793
diff
changeset
|
2121 random characters that are different in each Emacs job. The result is |
8757023049af
(Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents:
61793
diff
changeset
|
2122 guaranteed to be a newly created empty file. On MS-DOS, this function |
8757023049af
(Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents:
61793
diff
changeset
|
2123 can truncate the @var{string} prefix to fit into the 8+3 file-name |
8757023049af
(Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents:
61793
diff
changeset
|
2124 limits. If @var{prefix} is a relative file name, it is expanded |
8757023049af
(Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents:
61793
diff
changeset
|
2125 against @code{temporary-file-directory}. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2126 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2127 @example |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2128 @group |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2129 (make-temp-file "foo") |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2130 @result{} "/tmp/foo232J6v" |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2131 @end group |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2132 @end example |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2133 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2134 When @code{make-temp-file} returns, the file has been created and is |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2135 empty. At that point, you should write the intended contents into the |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2136 file. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2137 |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2138 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2139 empty directory instead of an empty file. It returns the file name, |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2140 not the directory name, of that directory. @xref{Directory Names}. |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2141 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2142 If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2143 the end of the file name. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2144 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2145 To prevent conflicts among different libraries running in the same |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2146 Emacs, each Lisp program that uses @code{make-temp-file} should have its |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2147 own @var{prefix}. The number added to the end of @var{prefix} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2148 distinguishes between the same application running in different Emacs |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2149 jobs. Additional added characters permit a large number of distinct |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2150 names even in one Emacs job. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2151 @end defun |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2152 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2153 The default directory for temporary files is controlled by the |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2154 variable @code{temporary-file-directory}. This variable gives the user |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2155 a uniform way to specify the directory for all temporary files. Some |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2156 programs use @code{small-temporary-file-directory} instead, if that is |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2157 non-@code{nil}. To use it, you should expand the prefix against |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2158 the proper directory before calling @code{make-temp-file}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2159 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2160 In older Emacs versions where @code{make-temp-file} does not exist, |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2161 you should use @code{make-temp-name} instead: |
6555 | 2162 |
2163 @example | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2164 (make-temp-name |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2165 (expand-file-name @var{name-of-application} |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2166 temporary-file-directory)) |
6555 | 2167 @end example |
2168 | |
2169 @defun make-temp-name string | |
61795
8757023049af
(Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents:
61793
diff
changeset
|
2170 This function generates a string that can be used as a unique file |
8757023049af
(Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents:
61793
diff
changeset
|
2171 name. The name starts with @var{string}, and has several random |
8757023049af
(Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents:
61793
diff
changeset
|
2172 characters appended to it, which are different in each Emacs job. It |
8757023049af
(Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents:
61793
diff
changeset
|
2173 is like @code{make-temp-file} except that it just constructs a name, |
8757023049af
(Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents:
61793
diff
changeset
|
2174 and does not create a file. Another difference is that @var{string} |
8757023049af
(Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents:
61793
diff
changeset
|
2175 should be an absolute file name. On MS-DOS, this function can |
8757023049af
(Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents:
61793
diff
changeset
|
2176 truncate the @var{string} prefix to fit into the 8+3 file-name limits. |
6555 | 2177 @end defun |
2178 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2179 @defvar temporary-file-directory |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2180 @cindex @code{TMPDIR} environment variable |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2181 @cindex @code{TMP} environment variable |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2182 @cindex @code{TEMP} environment variable |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2183 This variable specifies the directory name for creating temporary files. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2184 Its value should be a directory name (@pxref{Directory Names}), but it |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2185 is good for Lisp programs to cope if the value is a directory's file |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2186 name instead. Using the value as the second argument to |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2187 @code{expand-file-name} is a good way to achieve that. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2188 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2189 The default value is determined in a reasonable way for your operating |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2190 system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2191 environment variables, with a fall-back to a system-dependent name if |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2192 none of these variables is defined. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2193 |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2194 Even if you do not use @code{make-temp-file} to create the temporary |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2195 file, you should still use this variable to decide which directory to |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2196 put the file in. However, if you expect the file to be small, you |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2197 should use @code{small-temporary-file-directory} first if that is |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2198 non-@code{nil}. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2199 @end defvar |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2200 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2201 @defvar small-temporary-file-directory |
60444
78a2cd972ba1
(Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents:
59877
diff
changeset
|
2202 This variable specifies the directory name for |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2203 creating certain temporary files, which are likely to be small. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2204 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2205 If you want to write a temporary file which is likely to be small, you |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2206 should compute the directory like this: |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2207 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2208 @example |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2209 (make-temp-file |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2210 (expand-file-name @var{prefix} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2211 (or small-temporary-file-directory |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2212 temporary-file-directory))) |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2213 @end example |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2214 @end defvar |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2215 |
6555 | 2216 @node File Name Completion |
2217 @subsection File Name Completion | |
2218 @cindex file name completion subroutines | |
2219 @cindex completion, file name | |
2220 | |
2221 This section describes low-level subroutines for completing a file | |
71489
dc87235a6d17
(File Name Completion): Point user to the node "Reading File Names".
Nick Roberts <nickrob@snap.net.nz>
parents:
71463
diff
changeset
|
2222 name. For higher level functions, see @ref{Reading File Names}. |
6555 | 2223 |
2224 @defun file-name-all-completions partial-filename directory | |
2225 This function returns a list of all possible completions for a file | |
2226 whose name starts with @var{partial-filename} in directory | |
2227 @var{directory}. The order of the completions is the order of the files | |
2228 in the directory, which is unpredictable and conveys no useful | |
2229 information. | |
2230 | |
2231 The argument @var{partial-filename} must be a file name containing no | |
28635
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
2232 directory part and no slash (or backslash on some systems). The current |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
2233 buffer's default directory is prepended to @var{directory}, if |
cda2b6ed6aec
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
28608
diff
changeset
|
2234 @var{directory} is not absolute. |
6555 | 2235 |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
2236 In the following example, suppose that @file{~rms/lewis} is the current |
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
2237 default directory, and has five files whose names begin with @samp{f}: |
6555 | 2238 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and |
2239 @file{file.c.~2~}.@refill | |
2240 | |
2241 @example | |
2242 @group | |
2243 (file-name-all-completions "f" "") | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
47980
diff
changeset
|
2244 @result{} ("foo" "file~" "file.c.~2~" |
6555 | 2245 "file.c.~1~" "file.c") |
2246 @end group | |
2247 | |
2248 @group | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
47980
diff
changeset
|
2249 (file-name-all-completions "fo" "") |
6555 | 2250 @result{} ("foo") |
2251 @end group | |
2252 @end example | |
2253 @end defun | |
2254 | |
74688
29c73296a044
(File Name Completion): Document PREDICATE arg to file-name-completion.
Richard M. Stallman <rms@gnu.org>
parents:
71957
diff
changeset
|
2255 @defun file-name-completion filename directory &optional predicate |
6555 | 2256 This function completes the file name @var{filename} in directory |
2257 @var{directory}. It returns the longest prefix common to all file names | |
74688
29c73296a044
(File Name Completion): Document PREDICATE arg to file-name-completion.
Richard M. Stallman <rms@gnu.org>
parents:
71957
diff
changeset
|
2258 in directory @var{directory} that start with @var{filename}. If |
29c73296a044
(File Name Completion): Document PREDICATE arg to file-name-completion.
Richard M. Stallman <rms@gnu.org>
parents:
71957
diff
changeset
|
2259 @var{predicate} is non-@code{nil} then it ignores possible completions |
29c73296a044
(File Name Completion): Document PREDICATE arg to file-name-completion.
Richard M. Stallman <rms@gnu.org>
parents:
71957
diff
changeset
|
2260 that don't satisfy @var{predicate}, after calling that function |
29c73296a044
(File Name Completion): Document PREDICATE arg to file-name-completion.
Richard M. Stallman <rms@gnu.org>
parents:
71957
diff
changeset
|
2261 with one argument, the expanded absolute file name. |
6555 | 2262 |
2263 If only one match exists and @var{filename} matches it exactly, the | |
2264 function returns @code{t}. The function returns @code{nil} if directory | |
2265 @var{directory} contains no name starting with @var{filename}. | |
2266 | |
2267 In the following example, suppose that the current default directory | |
2268 has five files whose names begin with @samp{f}: @file{foo}, | |
2269 @file{file~}, @file{file.c}, @file{file.c.~1~}, and | |
2270 @file{file.c.~2~}.@refill | |
2271 | |
2272 @example | |
2273 @group | |
2274 (file-name-completion "fi" "") | |
2275 @result{} "file" | |
2276 @end group | |
2277 | |
2278 @group | |
2279 (file-name-completion "file.c.~1" "") | |
2280 @result{} "file.c.~1~" | |
2281 @end group | |
2282 | |
2283 @group | |
2284 (file-name-completion "file.c.~1~" "") | |
2285 @result{} t | |
2286 @end group | |
2287 | |
2288 @group | |
2289 (file-name-completion "file.c.~3" "") | |
2290 @result{} nil | |
2291 @end group | |
2292 @end example | |
2293 @end defun | |
2294 | |
2295 @defopt completion-ignored-extensions | |
2296 @code{file-name-completion} usually ignores file names that end in any | |
2297 string in this list. It does not ignore them when all the possible | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2298 completions end in one of these suffixes. This variable has no effect |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2299 on @code{file-name-all-completions}.@refill |
6555 | 2300 |
2301 A typical value might look like this: | |
2302 | |
2303 @example | |
2304 @group | |
2305 completion-ignored-extensions | |
2306 @result{} (".o" ".elc" "~" ".dvi") | |
2307 @end group | |
2308 @end example | |
39883
416c492df7c3
(File Name Completion): Document the significance of
Eli Zaretskii <eliz@gnu.org>
parents:
39296
diff
changeset
|
2309 |
416c492df7c3
(File Name Completion): Document the significance of
Eli Zaretskii <eliz@gnu.org>
parents:
39296
diff
changeset
|
2310 If an element of @code{completion-ignored-extensions} ends in a slash |
416c492df7c3
(File Name Completion): Document the significance of
Eli Zaretskii <eliz@gnu.org>
parents:
39296
diff
changeset
|
2311 @samp{/}, it signals a directory. The elements which do @emph{not} end |
416c492df7c3
(File Name Completion): Document the significance of
Eli Zaretskii <eliz@gnu.org>
parents:
39296
diff
changeset
|
2312 in a slash will never match a directory; thus, the above value will not |
416c492df7c3
(File Name Completion): Document the significance of
Eli Zaretskii <eliz@gnu.org>
parents:
39296
diff
changeset
|
2313 filter out a directory named @file{foo.elc}. |
6555 | 2314 @end defopt |
2315 | |
15765
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2316 @node Standard File Names |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2317 @subsection Standard File Names |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2318 |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2319 Most of the file names used in Lisp programs are entered by the user. |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2320 But occasionally a Lisp program needs to specify a standard file name |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2321 for a particular use---typically, to hold customization information |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2322 about each user. For example, abbrev definitions are stored (by |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2323 default) in the file @file{~/.abbrev_defs}; the @code{completion} |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2324 package stores completions in the file @file{~/.completions}. These are |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2325 two of the many standard file names used by parts of Emacs for certain |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2326 purposes. |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2327 |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2328 Various operating systems have their own conventions for valid file |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2329 names and for which file names to use for user profile data. A Lisp |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2330 program which reads a file using a standard file name ought to use, on |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2331 each type of system, a file name suitable for that system. The function |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2332 @code{convert-standard-filename} makes this easy to do. |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2333 |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2334 @defun convert-standard-filename filename |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2335 This function alters the file name @var{filename} to fit the conventions |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2336 of the operating system in use, and returns the result as a new string. |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2337 @end defun |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2338 |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2339 The recommended way to specify a standard file name in a Lisp program |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2340 is to choose a name which fits the conventions of GNU and Unix systems, |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2341 usually with a nondirectory part that starts with a period, and pass it |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2342 to @code{convert-standard-filename} instead of using it directly. Here |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2343 is an example from the @code{completion} package: |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2344 |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2345 @example |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2346 (defvar save-completions-file-name |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2347 (convert-standard-filename "~/.completions") |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2348 "*The file name to save completions to.") |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2349 @end example |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2350 |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2351 On GNU and Unix systems, and on some other systems as well, |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2352 @code{convert-standard-filename} returns its argument unchanged. On |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2353 some other systems, it alters the name to fit the system's conventions. |
15765
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2354 |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2355 For example, on MS-DOS the alterations made by this function include |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2356 converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2357 middle of the name to @samp{.} if there is no other @samp{.}, inserting |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2358 a @samp{.} after eight characters if there is none, and truncating to |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2359 three characters after the @samp{.}. (It makes other changes as well.) |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2360 Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2361 @file{.completions} becomes @file{_complet.ion}. |
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2362 |
6555 | 2363 @node Contents of Directories |
2364 @section Contents of Directories | |
2365 @cindex directory-oriented functions | |
2366 @cindex file names in directory | |
2367 | |
2368 A directory is a kind of file that contains other files entered under | |
2369 various names. Directories are a feature of the file system. | |
2370 | |
2371 Emacs can list the names of the files in a directory as a Lisp list, | |
2372 or display the names in a buffer using the @code{ls} shell command. In | |
2373 the latter case, it can optionally display information about each file, | |
2374 depending on the options passed to the @code{ls} command. | |
2375 | |
2376 @defun directory-files directory &optional full-name match-regexp nosort | |
2377 This function returns a list of the names of the files in the directory | |
2378 @var{directory}. By default, the list is in alphabetical order. | |
2379 | |
2380 If @var{full-name} is non-@code{nil}, the function returns the files' | |
2381 absolute file names. Otherwise, it returns the names relative to | |
2382 the specified directory. | |
2383 | |
2384 If @var{match-regexp} is non-@code{nil}, this function returns only | |
2385 those file names that contain a match for that regular expression---the | |
71463
f1944cae0a63
(Contents of Directories): Document case-insensitive behavior on respective
Eli Zaretskii <eliz@gnu.org>
parents:
71003
diff
changeset
|
2386 other file names are excluded from the list. On case-insensitive |
f1944cae0a63
(Contents of Directories): Document case-insensitive behavior on respective
Eli Zaretskii <eliz@gnu.org>
parents:
71003
diff
changeset
|
2387 filesystems, the regular expression matching is case-insensitive. |
6555 | 2388 |
2389 @c Emacs 19 feature | |
2390 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort | |
2391 the list, so you get the file names in no particular order. Use this if | |
2392 you want the utmost possible speed and don't care what order the files | |
2393 are processed in. If the order of processing is visible to the user, | |
2394 then the user will probably be happier if you do sort the names. | |
2395 | |
2396 @example | |
2397 @group | |
2398 (directory-files "~lewis") | |
2399 @result{} ("#foo#" "#foo.el#" "." ".." | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
47980
diff
changeset
|
2400 "dired-mods.el" "files.texi" |
6555 | 2401 "files.texi.~1~") |
2402 @end group | |
2403 @end example | |
2404 | |
2405 An error is signaled if @var{directory} is not the name of a directory | |
2406 that can be read. | |
2407 @end defun | |
2408 | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2409 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format |
53425
bd30a9882e31
(Contents of Directories):
Richard M. Stallman <rms@gnu.org>
parents:
53109
diff
changeset
|
2410 This is similar to @code{directory-files} in deciding which files |
bd30a9882e31
(Contents of Directories):
Richard M. Stallman <rms@gnu.org>
parents:
53109
diff
changeset
|
2411 to report on and how to report their names. However, instead |
bd30a9882e31
(Contents of Directories):
Richard M. Stallman <rms@gnu.org>
parents:
53109
diff
changeset
|
2412 of returning a list of file names, it returns for each file a |
bd30a9882e31
(Contents of Directories):
Richard M. Stallman <rms@gnu.org>
parents:
53109
diff
changeset
|
2413 list @code{(@var{filename} . @var{attributes})}, where @var{attributes} |
bd30a9882e31
(Contents of Directories):
Richard M. Stallman <rms@gnu.org>
parents:
53109
diff
changeset
|
2414 is what @code{file-attributes} would return for that file. |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2415 The optional argument @var{id-format} has the same meaning as the |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2416 corresponding argument to @code{file-attributes} (@pxref{Definition |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2417 of file-attributes}). |
53425
bd30a9882e31
(Contents of Directories):
Richard M. Stallman <rms@gnu.org>
parents:
53109
diff
changeset
|
2418 @end defun |
bd30a9882e31
(Contents of Directories):
Richard M. Stallman <rms@gnu.org>
parents:
53109
diff
changeset
|
2419 |
6555 | 2420 @defun file-name-all-versions file dirname |
2421 This function returns a list of all versions of the file named | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2422 @var{file} in directory @var{dirname}. It is only available on VMS. |
6555 | 2423 @end defun |
2424 | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2425 @defun file-expand-wildcards pattern &optional full |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2426 This function expands the wildcard pattern @var{pattern}, returning |
24952 | 2427 a list of file names that match it. |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2428 |
24952 | 2429 If @var{pattern} is written as an absolute file name, |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2430 the values are absolute also. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2431 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2432 If @var{pattern} is written as a relative file name, it is interpreted |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2433 relative to the current default directory. The file names returned are |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2434 normally also relative to the current default directory. However, if |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2435 @var{full} is non-@code{nil}, they are absolute. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2436 @end defun |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
2437 |
6555 | 2438 @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
|
2439 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
|
2440 directory @var{file}, formatted with @code{ls} according to |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2441 @var{switches}. It leaves point after the inserted text. |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2442 @var{switches} may be a string of options, or a list of strings |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2443 representing individual options. |
6555 | 2444 |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2445 The argument @var{file} may be either a directory name or a file |
6555 | 2446 specification including wildcard characters. If @var{wildcard} is |
2447 non-@code{nil}, that means treat @var{file} as a file specification with | |
2448 wildcards. | |
2449 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2450 If @var{full-directory-p} is non-@code{nil}, that means the directory |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2451 listing is expected to show the full contents of a directory. You |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2452 should specify @code{t} when @var{file} is a directory and switches do |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2453 not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2454 describe a directory itself as a file, rather than showing its |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2455 contents.) |
6555 | 2456 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2457 On most systems, this function works by running a directory listing |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2458 program whose name is in the variable @code{insert-directory-program}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2459 If @var{wildcard} is non-@code{nil}, it also runs the shell specified by |
6555 | 2460 @code{shell-file-name}, to expand the wildcards. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2461 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2462 MS-DOS and MS-Windows systems usually lack the standard Unix program |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2463 @code{ls}, so this function emulates the standard Unix program @code{ls} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2464 with Lisp code. |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2465 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2466 As a technical detail, when @var{switches} contains the long |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2467 @samp{--dired} option, @code{insert-directory} treats it specially, |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2468 for the sake of dired. However, the normally equivalent short |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2469 @samp{-D} option is just passed on to @code{insert-directory-program}, |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2470 as any other option. |
6555 | 2471 @end defun |
2472 | |
2473 @defvar insert-directory-program | |
2474 This variable's value is the program to run to generate a directory listing | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2475 for the function @code{insert-directory}. It is ignored on systems |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2476 which generate the listing with Lisp code. |
6555 | 2477 @end defvar |
2478 | |
2479 @node Create/Delete Dirs | |
2480 @section Creating and Deleting Directories | |
76841 | 2481 @cindex creating and deleting directories |
6555 | 2482 @c Emacs 19 features |
2483 | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2484 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
|
2485 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
|
2486 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
|
2487 delete directories. |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2488 |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25751
diff
changeset
|
2489 @defun make-directory dirname &optional parents |
6555 | 2490 This function creates a directory named @var{dirname}. |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2491 If @var{parents} is non-@code{nil}, as is always the case in an |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2492 interactive call, that means to create the parent directories first, |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2493 if they don't already exist. |
6555 | 2494 @end defun |
2495 | |
2496 @defun delete-directory dirname | |
2497 This function deletes the directory named @var{dirname}. The function | |
2498 @code{delete-file} does not work for files that are directories; you | |
12098 | 2499 must use @code{delete-directory} for them. If the directory contains |
2500 any files, @code{delete-directory} signals an error. | |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2501 |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2502 This function only follows symbolic links at the level of parent |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2503 directories. |
6555 | 2504 @end defun |
2505 | |
2506 @node Magic File Names | |
2507 @section Making Certain File Names ``Magic'' | |
2508 @cindex magic file names | |
2509 | |
2510 @c Emacs 19 feature | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2511 You can implement special handling for certain file names. This is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2512 called making those names @dfn{magic}. The principal use for this |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2513 feature is in implementing remote file names (@pxref{Remote Files,, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2514 Remote Files, emacs, The GNU Emacs Manual}). |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2515 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2516 To define a kind of magic file name, you must supply a regular |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2517 expression to define the class of names (all those that match the |
6555 | 2518 regular expression), plus a handler that implements all the primitive |
2519 Emacs file operations for file names that do match. | |
2520 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2521 The variable @code{file-name-handler-alist} holds a list of handlers, |
6555 | 2522 together with regular expressions that determine when to apply each |
2523 handler. Each element has this form: | |
2524 | |
2525 @example | |
2526 (@var{regexp} . @var{handler}) | |
2527 @end example | |
2528 | |
2529 @noindent | |
2530 All the Emacs primitives for file access and file name transformation | |
2531 check the given file name against @code{file-name-handler-alist}. If | |
2532 the file name matches @var{regexp}, the primitives handle that file by | |
2533 calling @var{handler}. | |
2534 | |
61949
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2535 The first argument given to @var{handler} is the name of the |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2536 primitive, as a symbol; the remaining arguments are the arguments that |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2537 were passed to that primitive. (The first of these arguments is most |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2538 often the file name itself.) For example, if you do this: |
6555 | 2539 |
2540 @example | |
2541 (file-exists-p @var{filename}) | |
2542 @end example | |
2543 | |
2544 @noindent | |
2545 and @var{filename} has handler @var{handler}, then @var{handler} is | |
2546 called like this: | |
2547 | |
2548 @example | |
2549 (funcall @var{handler} 'file-exists-p @var{filename}) | |
2550 @end example | |
2551 | |
61949
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2552 When a function takes two or more arguments that must be file names, |
37582
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2553 it checks each of those names for a handler. For example, if you do |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2554 this: |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2555 |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2556 @example |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2557 (expand-file-name @var{filename} @var{dirname}) |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2558 @end example |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2559 |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2560 @noindent |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2561 then it checks for a handler for @var{filename} and then for a handler |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2562 for @var{dirname}. In either case, the @var{handler} is called like |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2563 this: |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2564 |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2565 @example |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2566 (funcall @var{handler} 'expand-file-name @var{filename} @var{dirname}) |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2567 @end example |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2568 |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2569 @noindent |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2570 The @var{handler} then needs to figure out whether to handle |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2571 @var{filename} or @var{dirname}. |
fdf780ddf0ae
Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents:
32859
diff
changeset
|
2572 |
61949
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2573 If the specified file name matches more than one handler, the one |
51913
3abc365e9d90
(Changing Files): copy-file allows dir as NEWNAME.
Richard M. Stallman <rms@gnu.org>
parents:
51793
diff
changeset
|
2574 whose match starts last in the file name gets precedence. This rule |
3abc365e9d90
(Changing Files): copy-file allows dir as NEWNAME.
Richard M. Stallman <rms@gnu.org>
parents:
51793
diff
changeset
|
2575 is chosen so that handlers for jobs such as uncompression are handled |
3abc365e9d90
(Changing Files): copy-file allows dir as NEWNAME.
Richard M. Stallman <rms@gnu.org>
parents:
51793
diff
changeset
|
2576 first, before handlers for jobs such as remote file access. |
3abc365e9d90
(Changing Files): copy-file allows dir as NEWNAME.
Richard M. Stallman <rms@gnu.org>
parents:
51793
diff
changeset
|
2577 |
75476
330094c564c4
(File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents:
75250
diff
changeset
|
2578 Here are the operations that a magic file name handler gets to handle: |
6555 | 2579 |
27193 | 2580 @ifnottex |
6555 | 2581 @noindent |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2582 @code{access-file}, @code{add-name-to-file}, |
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2583 @code{byte-compiler-base-file-name},@* |
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2584 @code{copy-file}, @code{delete-directory}, |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2585 @code{delete-file}, |
12226 | 2586 @code{diff-latest-backup-file}, |
6555 | 2587 @code{directory-file-name}, |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2588 @code{directory-files}, |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2589 @code{directory-files-and-attributes}, |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
2590 @code{dired-call-process}, |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2591 @code{dired-compress-file}, @code{dired-uncache},@* |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2592 @code{expand-file-name}, |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2593 @code{file-accessible-directory-p}, |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2594 @code{file-attributes}, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2595 @code{file-directory-p}, |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2596 @code{file-executable-p}, @code{file-exists-p}, |
55847
d87f8236b6fd
files.texi (Magic File Names): Add `file-remote-p' as operation
Michael Albinus <michael.albinus@gmx.de>
parents:
55192
diff
changeset
|
2597 @code{file-local-copy}, @code{file-remote-p}, |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2598 @code{file-modes}, @code{file-name-all-completions}, |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2599 @code{file-name-as-directory}, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2600 @code{file-name-completion}, |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
2601 @code{file-name-directory}, |
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
2602 @code{file-name-nondirectory}, |
6555 | 2603 @code{file-name-sans-versions}, @code{file-newer-than-file-p}, |
15765
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2604 @code{file-ownership-preserved-p}, |
11626
0b86aef0c387
Mention file-regular-p operation.
Richard M. Stallman <rms@gnu.org>
parents:
8364
diff
changeset
|
2605 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, |
12226 | 2606 @code{file-truename}, @code{file-writable-p}, |
15765
8cc15b664c4c
New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents:
14152
diff
changeset
|
2607 @code{find-backup-file-name}, |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2608 @code{find-file-noselect},@* |
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2609 @code{get-file-buffer}, |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2610 @code{insert-directory}, |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2611 @code{insert-file-contents},@* |
65248
0f994edbec5e
Make `make-auto-save-file-name' a magic operation.
Michael Albinus <michael.albinus@gmx.de>
parents:
64889
diff
changeset
|
2612 @code{load}, |
0f994edbec5e
Make `make-auto-save-file-name' a magic operation.
Michael Albinus <michael.albinus@gmx.de>
parents:
64889
diff
changeset
|
2613 @code{make-auto-save-file-name}, |
0f994edbec5e
Make `make-auto-save-file-name' a magic operation.
Michael Albinus <michael.albinus@gmx.de>
parents:
64889
diff
changeset
|
2614 @code{make-directory}, |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2615 @code{make-directory-internal}, |
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2616 @code{make-symbolic-link},@* |
55192
dd5538a91d27
(Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents:
54861
diff
changeset
|
2617 @code{rename-file}, @code{set-file-modes}, @code{set-file-times}, |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2618 @code{set-visited-file-modtime}, @code{shell-command}, |
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2619 @code{substitute-in-file-name},@* |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2620 @code{unhandled-file-name-directory}, |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
15913
diff
changeset
|
2621 @code{vc-registered}, |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2622 @code{verify-visited-file-modtime},@* |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2623 @code{write-region}. |
27193 | 2624 @end ifnottex |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2625 @iftex |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2626 @noindent |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2627 @flushleft |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2628 @code{access-file}, @code{add-name-to-file}, |
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2629 @code{byte-com@discretionary{}{}{}piler-base-file-name}, |
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2630 @code{copy-file}, @code{delete-directory}, |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2631 @code{delete-file}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2632 @code{diff-latest-backup-file}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2633 @code{directory-file-name}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2634 @code{directory-files}, |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2635 @code{directory-files-and-at@discretionary{}{}{}tributes}, |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2636 @code{dired-call-process}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2637 @code{dired-compress-file}, @code{dired-uncache}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2638 @code{expand-file-name}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2639 @code{file-accessible-direc@discretionary{}{}{}tory-p}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2640 @code{file-attributes}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2641 @code{file-direct@discretionary{}{}{}ory-p}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2642 @code{file-executable-p}, @code{file-exists-p}, |
55847
d87f8236b6fd
files.texi (Magic File Names): Add `file-remote-p' as operation
Michael Albinus <michael.albinus@gmx.de>
parents:
55192
diff
changeset
|
2643 @code{file-local-copy}, @code{file-remote-p}, |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2644 @code{file-modes}, @code{file-name-all-completions}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2645 @code{file-name-as-directory}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2646 @code{file-name-completion}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2647 @code{file-name-directory}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2648 @code{file-name-nondirec@discretionary{}{}{}tory}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2649 @code{file-name-sans-versions}, @code{file-newer-than-file-p}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2650 @code{file-ownership-pre@discretionary{}{}{}served-p}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2651 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2652 @code{file-truename}, @code{file-writable-p}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2653 @code{find-backup-file-name}, |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2654 @code{find-file-noselect}, |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2655 @code{get-file-buffer}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2656 @code{insert-directory}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2657 @code{insert-file-contents}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2658 @code{load}, @code{make-direc@discretionary{}{}{}tory}, |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2659 @code{make-direc@discretionary{}{}{}tory-internal}, |
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2660 @code{make-symbolic-link}, |
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2661 @code{rename-file}, @code{set-file-modes}, |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2662 @code{set-visited-file-modtime}, @code{shell-command}, |
47980
5492d1831d2a
From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
47514
diff
changeset
|
2663 @code{substitute-in-file-name}, |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2664 @code{unhandled-file-name-directory}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2665 @code{vc-regis@discretionary{}{}{}tered}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2666 @code{verify-visited-file-modtime}, |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2667 @code{write-region}. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24952
diff
changeset
|
2668 @end flushleft |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
2669 @end iftex |
6555 | 2670 |
61949
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2671 Handlers for @code{insert-file-contents} typically need to clear the |
8118
56b5ed321f8d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2672 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
|
2673 @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
|
2674 unlocking the buffer if it is locked. |
56b5ed321f8d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2675 |
61949
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2676 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
|
2677 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
|
2678 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
|
2679 certain operation, it can reinvoke the primitive, to handle the |
71957
61cb5aae3bc3
Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents:
71709
diff
changeset
|
2680 operation ``in the usual way.'' It should always reinvoke the primitive |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7088
diff
changeset
|
2681 for an operation it does not recognize. Here's one way to do this: |
6555 | 2682 |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2683 @smallexample |
6555 | 2684 (defun my-file-handler (operation &rest args) |
2685 ;; @r{First check for the specific operations} | |
2686 ;; @r{that we have special handling for.} | |
2687 (cond ((eq operation 'insert-file-contents) @dots{}) | |
2688 ((eq operation 'write-region) @dots{}) | |
2689 @dots{} | |
2690 ;; @r{Handle any operation we don't know about.} | |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2691 (t (let ((inhibit-file-name-handlers |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
47980
diff
changeset
|
2692 (cons 'my-file-handler |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2693 (and (eq inhibit-file-name-operation operation) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2694 inhibit-file-name-handlers))) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2695 (inhibit-file-name-operation operation)) |
6555 | 2696 (apply operation args))))) |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2697 @end smallexample |
6555 | 2698 |
61949
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2699 When a handler function decides to call the ordinary Emacs primitive for |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2700 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
|
2701 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
|
2702 example above shows how to do this, with the variables |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2703 @code{inhibit-file-name-handlers} and |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2704 @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
|
2705 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
|
2706 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
|
2707 each have handlers. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2708 |
51020
417a9e80f335
(Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents:
50501
diff
changeset
|
2709 @kindex safe-magic (@r{property}) |
61949
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2710 Handlers that don't really do anything special for actual access to the |
51020
417a9e80f335
(Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents:
50501
diff
changeset
|
2711 file---such as the ones that implement completion of host names for |
417a9e80f335
(Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents:
50501
diff
changeset
|
2712 remote file names---should have a non-@code{nil} @code{safe-magic} |
417a9e80f335
(Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents:
50501
diff
changeset
|
2713 property. For instance, Emacs normally ``protects'' directory names |
417a9e80f335
(Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents:
50501
diff
changeset
|
2714 it finds in @code{PATH} from becoming magic, if they look like magic |
417a9e80f335
(Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents:
50501
diff
changeset
|
2715 file names, by prefixing them with @samp{/:}. But if the handler that |
417a9e80f335
(Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents:
50501
diff
changeset
|
2716 would be used for them has a non-@code{nil} @code{safe-magic} |
417a9e80f335
(Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents:
50501
diff
changeset
|
2717 property, the @samp{/:} is not added. |
417a9e80f335
(Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents:
50501
diff
changeset
|
2718 |
61949
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2719 @kindex operations (@r{property}) |
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2720 A file name handler can have an @code{operations} property to |
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2721 declare which operations it handles in a nontrivial way. If this |
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2722 property has a non-@code{nil} value, it should be a list of |
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2723 operations; then only those operations will call the handler. This |
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2724 avoids inefficiency, but its main purpose is for autoloaded handler |
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2725 functions, so that they won't be loaded except when they have real |
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2726 work to do. |
d0cfb9c978f9
(Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents:
61795
diff
changeset
|
2727 |
75476
330094c564c4
(File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents:
75250
diff
changeset
|
2728 Simply deferring all operations to the usual primitives does not |
330094c564c4
(File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents:
75250
diff
changeset
|
2729 work. For instance, if the file name handler applies to |
330094c564c4
(File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents:
75250
diff
changeset
|
2730 @code{file-exists-p}, then it must handle @code{load} itself, because |
330094c564c4
(File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents:
75250
diff
changeset
|
2731 the usual @code{load} code won't work properly in that case. However, |
330094c564c4
(File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents:
75250
diff
changeset
|
2732 if the handler uses the @code{operations} property to say it doesn't |
330094c564c4
(File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents:
75250
diff
changeset
|
2733 handle @code{file-exists-p}, then it need not handle @code{load} |
330094c564c4
(File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents:
75250
diff
changeset
|
2734 nontrivially. |
330094c564c4
(File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents:
75250
diff
changeset
|
2735 |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2736 @defvar inhibit-file-name-handlers |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2737 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
|
2738 for a certain operation. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2739 @end defvar |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2740 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2741 @defvar inhibit-file-name-operation |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2742 The operation for which certain handlers are presently inhibited. |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2743 @end defvar |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2744 |
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2745 @defun find-file-name-handler file operation |
66737
09cf7401d368
(Magic File Names): find-file-name-handler checks the
Richard M. Stallman <rms@gnu.org>
parents:
66144
diff
changeset
|
2746 This function returns the handler function for file name @var{file}, |
09cf7401d368
(Magic File Names): find-file-name-handler checks the
Richard M. Stallman <rms@gnu.org>
parents:
66144
diff
changeset
|
2747 or @code{nil} if there is none. The argument @var{operation} should |
09cf7401d368
(Magic File Names): find-file-name-handler checks the
Richard M. Stallman <rms@gnu.org>
parents:
66144
diff
changeset
|
2748 be the operation to be performed on the file---the value you will pass |
09cf7401d368
(Magic File Names): find-file-name-handler checks the
Richard M. Stallman <rms@gnu.org>
parents:
66144
diff
changeset
|
2749 to the handler as its first argument when you call it. If |
09cf7401d368
(Magic File Names): find-file-name-handler checks the
Richard M. Stallman <rms@gnu.org>
parents:
66144
diff
changeset
|
2750 @var{operation} equals @code{inhibit-file-name-operation}, or if it is |
09cf7401d368
(Magic File Names): find-file-name-handler checks the
Richard M. Stallman <rms@gnu.org>
parents:
66144
diff
changeset
|
2751 not found in the @code{operations} property of the handler, this |
09cf7401d368
(Magic File Names): find-file-name-handler checks the
Richard M. Stallman <rms@gnu.org>
parents:
66144
diff
changeset
|
2752 function returns @code{nil}. |
6555 | 2753 @end defun |
2754 | |
2755 @defun file-local-copy filename | |
52143
3b706f94b559
(Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents:
52003
diff
changeset
|
2756 This function copies file @var{filename} to an ordinary non-magic file |
3b706f94b559
(Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents:
52003
diff
changeset
|
2757 on the local machine, if it isn't on the local machine already. Magic |
3b706f94b559
(Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents:
52003
diff
changeset
|
2758 file names should handle the @code{file-local-copy} operation if they |
3b706f94b559
(Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents:
52003
diff
changeset
|
2759 refer to files on other machines. A magic file name that is used for |
3b706f94b559
(Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents:
52003
diff
changeset
|
2760 other purposes than remote file access should not handle |
3b706f94b559
(Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents:
52003
diff
changeset
|
2761 @code{file-local-copy}; then this function will treat the file as |
3b706f94b559
(Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents:
52003
diff
changeset
|
2762 local. |
3b706f94b559
(Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents:
52003
diff
changeset
|
2763 |
3b706f94b559
(Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents:
52003
diff
changeset
|
2764 If @var{filename} is local, whether magic or not, this function does |
3b706f94b559
(Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents:
52003
diff
changeset
|
2765 nothing and returns @code{nil}. Otherwise it returns the file name |
3b706f94b559
(Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents:
52003
diff
changeset
|
2766 of the local copy file. |
3b706f94b559
(Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents:
52003
diff
changeset
|
2767 @end defun |
3b706f94b559
(Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents:
52003
diff
changeset
|
2768 |
3b706f94b559
(Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents:
52003
diff
changeset
|
2769 @defun file-remote-p filename |
56322
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
2770 This function tests whether @var{filename} is a remote file. If |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
2771 @var{filename} is local (not remote), the return value is @code{nil}. |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
2772 If @var{filename} is indeed remote, the return value is a string that |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
2773 identifies the remote system. |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
2774 |
63583
99e9892a51d9
Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents:
62856
diff
changeset
|
2775 This identifier string can include a host name and a user name, as |
99e9892a51d9
Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents:
62856
diff
changeset
|
2776 well as characters designating the method used to access the remote |
99e9892a51d9
Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents:
62856
diff
changeset
|
2777 system. For example, the remote identifier string for the filename |
56322
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
2778 @code{/ssh:user@@host:/some/file} is @code{/ssh:user@@host:}. |
56321
904bb1836ccd
(Magic File Names): `file-remote-p' returns an identifier of the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
56231
diff
changeset
|
2779 |
904bb1836ccd
(Magic File Names): `file-remote-p' returns an identifier of the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
56231
diff
changeset
|
2780 If @code{file-remote-p} returns the same identifier for two different |
56322
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
2781 filenames, that means they are stored on the same file system and can |
56321
904bb1836ccd
(Magic File Names): `file-remote-p' returns an identifier of the
Kai Großjohann <kgrossjo@eu.uu.net>
parents:
56231
diff
changeset
|
2782 be accessed locally with respect to each other. This means, for |
56322
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
2783 example, that it is possible to start a remote process accessing both |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
2784 files at the same time. Implementors of file handlers need to ensure |
f597c982349e
(Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents:
56321
diff
changeset
|
2785 this principle is valid. |
6555 | 2786 @end defun |
2787 | |
2788 @defun unhandled-file-name-directory filename | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2789 This function returns the name of a directory that is not magic. It |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2790 uses the directory part of @var{filename} if that is not magic. For a |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2791 magic file name, it invokes the file name handler, which therefore |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2792 decides what value to return. |
6555 | 2793 |
2794 This is useful for running a subprocess; every subprocess must have a | |
2795 non-magic directory to serve as its current directory, and this function | |
2796 is a good way to come up with one. | |
2797 @end defun | |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2798 |
12067 | 2799 @node Format Conversion |
2800 @section File Format Conversion | |
2801 | |
2802 @cindex file format conversion | |
2803 @cindex encoding file formats | |
2804 @cindex decoding file formats | |
2805 The variable @code{format-alist} defines a list of @dfn{file formats}, | |
12098 | 2806 which describe textual representations used in files for the data (text, |
12067 | 2807 text-properties, and possibly other information) in an Emacs buffer. |
12098 | 2808 Emacs performs format conversion if appropriate when reading and writing |
2809 files. | |
12067 | 2810 |
2811 @defvar format-alist | |
2812 This list contains one format definition for each defined file format. | |
2813 @end defvar | |
2814 | |
2815 @cindex format definition | |
2816 Each format definition is a list of this form: | |
2817 | |
2818 @example | |
2819 (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn}) | |
2820 @end example | |
2821 | |
2822 Here is what the elements in a format definition mean: | |
2823 | |
2824 @table @var | |
2825 @item name | |
2826 The name of this format. | |
2827 | |
2828 @item doc-string | |
2829 A documentation string for the format. | |
2830 | |
2831 @item regexp | |
2832 A regular expression which is used to recognize files represented in | |
2833 this format. | |
2834 | |
2835 @item from-fn | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2836 A shell command or function to decode data in this format (to convert |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2837 file data into the usual Emacs data representation). |
12067 | 2838 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2839 A shell command is represented as a string; Emacs runs the command as a |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2840 filter to perform the conversion. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2841 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2842 If @var{from-fn} is a function, it is called with two arguments, @var{begin} |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2843 and @var{end}, which specify the part of the buffer it should convert. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2844 It should convert the text by editing it in place. Since this can |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2845 change the length of the text, @var{from-fn} should return the modified |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2846 end position. |
12067 | 2847 |
12098 | 2848 One responsibility of @var{from-fn} is to make sure that the beginning |
12067 | 2849 of the file no longer matches @var{regexp}. Otherwise it is likely to |
2850 get called again. | |
2851 | |
2852 @item to-fn | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2853 A shell command or function to encode data in this format---that is, to |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2854 convert the usual Emacs data representation into this format. |
12067 | 2855 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2856 If @var{to-fn} is a string, it is a shell command; Emacs runs the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2857 command as a filter to perform the conversion. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2858 |
77674
cf24d1dc433c
(Format Conversion): TO-FN gets three arguments.
Richard M. Stallman <rms@gnu.org>
parents:
77361
diff
changeset
|
2859 If @var{to-fn} is a function, it is called with three arguments: |
cf24d1dc433c
(Format Conversion): TO-FN gets three arguments.
Richard M. Stallman <rms@gnu.org>
parents:
77361
diff
changeset
|
2860 @var{begin} and @var{end}, which specify the part of the buffer it |
cf24d1dc433c
(Format Conversion): TO-FN gets three arguments.
Richard M. Stallman <rms@gnu.org>
parents:
77361
diff
changeset
|
2861 should convert, and @var{buffer}, which specifies which buffer. There |
cf24d1dc433c
(Format Conversion): TO-FN gets three arguments.
Richard M. Stallman <rms@gnu.org>
parents:
77361
diff
changeset
|
2862 are two ways it can do the conversion: |
12067 | 2863 |
2864 @itemize @bullet | |
2865 @item | |
2866 By editing the buffer in place. In this case, @var{to-fn} should | |
2867 return the end-position of the range of text, as modified. | |
2868 | |
2869 @item | |
2870 By returning a list of annotations. This is a list of elements of the | |
2871 form @code{(@var{position} . @var{string})}, where @var{position} is an | |
2872 integer specifying the relative position in the text to be written, and | |
2873 @var{string} is the annotation to add there. The list must be sorted in | |
2874 order of position when @var{to-fn} returns it. | |
2875 | |
2876 When @code{write-region} actually writes the text from the buffer to the | |
2877 file, it intermixes the specified annotations at the corresponding | |
2878 positions. All this takes place without modifying the buffer. | |
2879 @end itemize | |
2880 | |
2881 @item modify | |
2882 A flag, @code{t} if the encoding function modifies the buffer, and | |
2883 @code{nil} if it works by returning a list of annotations. | |
2884 | |
27259
c41efa6c4be1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
2885 @item mode-fn |
c41efa6c4be1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
2886 A minor-mode function to call after visiting a file converted from this |
c41efa6c4be1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
2887 format. The function is called with one argument, the integer 1; |
c41efa6c4be1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
2888 that tells a minor-mode function to enable the mode. |
12067 | 2889 @end table |
2890 | |
2891 The function @code{insert-file-contents} automatically recognizes file | |
2892 formats when it reads the specified file. It checks the text of the | |
2893 beginning of the file against the regular expressions of the format | |
2894 definitions, and if it finds a match, it calls the decoding function for | |
2895 that format. Then it checks all the known formats over again. | |
2896 It keeps checking them until none of them is applicable. | |
2897 | |
2898 Visiting a file, with @code{find-file-noselect} or the commands that use | |
2899 it, performs conversion likewise (because it calls | |
12098 | 2900 @code{insert-file-contents}); it also calls the mode function for each |
2901 format that it decodes. It stores a list of the format names in the | |
2902 buffer-local variable @code{buffer-file-format}. | |
12067 | 2903 |
2904 @defvar buffer-file-format | |
12098 | 2905 This variable states the format of the visited file. More precisely, |
2906 this is a list of the file format names that were decoded in the course | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2907 of visiting the current buffer's file. It is always buffer-local in all |
12067 | 2908 buffers. |
2909 @end defvar | |
2910 | |
2911 When @code{write-region} writes data into a file, it first calls the | |
12098 | 2912 encoding functions for the formats listed in @code{buffer-file-format}, |
2913 in the order of appearance in the list. | |
12067 | 2914 |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2915 @deffn Command format-write-file file format &optional confirm |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2916 This command writes the current buffer contents into the file |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2917 @var{file} in format @var{format}, and makes that format the default |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2918 for future saves of the buffer. The argument @var{format} is a list |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2919 of format names. Except for the @var{format} argument, this command |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2920 is similar to @code{write-file}. In particular, @var{confirm} has the |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2921 same meaning and interactive treatment as the corresponding argument |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2922 to @code{write-file}. @xref{Definition of write-file}. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2923 @end deffn |
12067 | 2924 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2925 @deffn Command format-find-file file format |
12226 | 2926 This command finds the file @var{file}, converting it according to |
2927 format @var{format}. It also makes @var{format} the default if the | |
2928 buffer is saved later. | |
2929 | |
2930 The argument @var{format} is a list of format names. If @var{format} is | |
2931 @code{nil}, no conversion takes place. Interactively, typing just | |
2932 @key{RET} for @var{format} specifies @code{nil}. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2933 @end deffn |
12226 | 2934 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2935 @deffn Command format-insert-file file format &optional beg end |
12226 | 2936 This command inserts the contents of file @var{file}, converting it |
2937 according to format @var{format}. If @var{beg} and @var{end} are | |
2938 non-@code{nil}, they specify which part of the file to read, as in | |
2939 @code{insert-file-contents} (@pxref{Reading from Files}). | |
2940 | |
2941 The return value is like what @code{insert-file-contents} returns: a | |
2942 list of the absolute file name and the length of the data inserted | |
2943 (after conversion). | |
2944 | |
2945 The argument @var{format} is a list of format names. If @var{format} is | |
2946 @code{nil}, no conversion takes place. Interactively, typing just | |
2947 @key{RET} for @var{format} specifies @code{nil}. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17919
diff
changeset
|
2948 @end deffn |
12226 | 2949 |
56981
54f19dd158e9
(Format Conversion): `auto-save-file-format' has been renamed
Luc Teirlinck <teirllm@auburn.edu>
parents:
56322
diff
changeset
|
2950 @defvar buffer-auto-save-file-format |
12067 | 2951 This variable specifies the format to use for auto-saving. Its value is |
2952 a list of format names, just like the value of | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2953 @code{buffer-file-format}; however, it is used instead of |
54861
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2954 @code{buffer-file-format} for writing auto-save files. If the value |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2955 is @code{t}, the default, auto-saving uses the same format as a |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2956 regular save in the same buffer. This variable is always buffer-local |
5af1398ad8e2
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54025
diff
changeset
|
2957 in all buffers. |
7088
5a93e6fb43a4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
2958 @end defvar |
52401 | 2959 |
2960 @ignore | |
2961 arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c | |
2962 @end ignore |