annotate lispref/files.texi @ 46343:fb71432c8a02

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