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