717 |
These functions test for permission to access a file in specific ways. |
These functions test for permission to access a file in specific ways. |
718 |
|
|
719 |
@defun file-exists-p filename |
@defun file-exists-p filename |
720 |
This function returns @code{t} if a file named @var{filename} appears to |
This function returns @code{t} if a file named @var{filename} appears |
721 |
exist. This does not mean you can necessarily read the file, only that |
to exist. This does not mean you can necessarily read the file, only |
722 |
you can find out its attributes. (On Unix and GNU/Linux, this is true |
that you can find out its attributes. (On Unix and GNU/Linux, this is |
723 |
if the file exists and you have execute permission on the containing |
true if the file exists and you have execute permission on the |
724 |
directories, regardless of the protection of the file itself.) |
containing directories, regardless of the protection of the file |
725 |
|
itself.) |
726 |
|
|
727 |
If the file does not exist, or if fascist access control policies |
If the file does not exist, or if fascist access control policies |
728 |
prevent you from finding the attributes of the file, this function |
prevent you from finding the attributes of the file, this function |
729 |
returns @code{nil}. |
returns @code{nil}. |
730 |
|
|
731 |
|
Directories are files, so @code{file-exists-p} returns @code{t} when |
732 |
|
given a directory name. However, symbolic links are treated |
733 |
|
specially; @code{file-exists-p} returns @code{t} for a symbolic link |
734 |
|
name only if the target file exists. |
735 |
@end defun |
@end defun |
736 |
|
|
737 |
@defun file-readable-p filename |
@defun file-readable-p filename |
865 |
|
|
866 |
@defun file-symlink-p filename |
@defun file-symlink-p filename |
867 |
@cindex file symbolic links |
@cindex file symbolic links |
868 |
If the file @var{filename} is a symbolic link, the @code{file-symlink-p} |
If the file @var{filename} is a symbolic link, the |
869 |
function returns the file name to which it is linked. This may be the |
@code{file-symlink-p} function returns the link target as a string. |
870 |
name of a text file, a directory, or even another symbolic link, or it |
(Determining the file name that the link points to from the target is |
871 |
may be a nonexistent file name. |
nontrivial.) |
872 |
|
|
873 |
If the file @var{filename} is not a symbolic link (or there is no such file), |
If the file @var{filename} is not a symbolic link (or there is no such file), |
874 |
@code{file-symlink-p} returns @code{nil}. |
@code{file-symlink-p} returns @code{nil}. |
948 |
@var{filename}. The argument must be an absolute file name. |
@var{filename}. The argument must be an absolute file name. |
949 |
@end defun |
@end defun |
950 |
|
|
951 |
@defun file-chase-links filename |
@defun file-chase-links filename &optional limit |
952 |
This function follows symbolic links, starting with @var{filename}, |
This function follows symbolic links, starting with @var{filename}, |
953 |
until it finds a file name which is not the name of a symbolic link. |
until it finds a file name which is not the name of a symbolic link. |
954 |
Then it returns that file name. |
Then it returns that file name. If you specify a number for |
955 |
|
@var{limit}, then after chasing through that many links, the function |
956 |
|
just returns what it as even if that is still a symbolic link. |
957 |
@end defun |
@end defun |
958 |
|
|
959 |
To illustrate the difference between @code{file-chase-links} and |
To illustrate the difference between @code{file-chase-links} and |
1278 |
|
|
1279 |
@deffn Command copy-file oldname newname &optional ok-if-exists time |
@deffn Command copy-file oldname newname &optional ok-if-exists time |
1280 |
This command copies the file @var{oldname} to @var{newname}. An |
This command copies the file @var{oldname} to @var{newname}. An |
1281 |
error is signaled if @var{oldname} does not exist. |
error is signaled if @var{oldname} does not exist. If @var{newname} |
1282 |
|
names a directory, it copies @var{oldname} into that directory, |
1283 |
|
preserving its final name component. |
1284 |
|
|
1285 |
If @var{time} is non-@code{nil}, then this function gives the new file |
If @var{time} is non-@code{nil}, then this function gives the new file |
1286 |
the same last-modified time that the old one has. (This works on only |
the same last-modified time that the old one has. (This works on only |
1287 |
some operating systems.) If setting the time gets an error, |
some operating systems.) If setting the time gets an error, |
1288 |
@code{copy-file} signals a @code{file-date-error} error. |
@code{copy-file} signals a @code{file-date-error} error. |
1289 |
|
|
1290 |
|
This function copies the file modes, too. |
1291 |
|
|
1292 |
In an interactive call, this function prompts for @var{filename} and |
In an interactive call, this function prompts for @var{filename} and |
1293 |
@var{newname} in the minibuffer; also, it requests confirmation if |
@var{newname} in the minibuffer; also, it requests confirmation if |
1294 |
@var{newname} already exists. |
@var{newname} already exists. |
1486 |
This function returns @var{filename}'s final ``extension,'' if any, |
This function returns @var{filename}'s final ``extension,'' if any, |
1487 |
after applying @code{file-name-sans-versions} to remove any |
after applying @code{file-name-sans-versions} to remove any |
1488 |
version/backup part. It returns @code{nil} for extensionless file |
version/backup part. It returns @code{nil} for extensionless file |
1489 |
names such as @file{foo}. If @var{period} is non-nil, then the |
names such as @file{foo}. If @var{period} is non-@code{nil}, then the |
1490 |
returned value includes the period that delimits the extension, and if |
returned value includes the period that delimits the extension, and if |
1491 |
@var{filename} has no extension, the value is @code{""}. If the last |
@var{filename} has no extension, the value is @code{""}. If the last |
1492 |
component of a file name begins with a @samp{.}, that @samp{.} doesn't |
component of a file name begins with a @samp{.}, that @samp{.} doesn't |
1813 |
|
|
1814 |
@defun substitute-in-file-name filename |
@defun substitute-in-file-name filename |
1815 |
This function replaces environment variables references in |
This function replaces environment variables references in |
1816 |
@var{filename} with the environment variable values. Following standard |
@var{filename} with the environment variable values. Following |
1817 |
Unix shell syntax, @samp{$} is the prefix to substitute an environment |
standard Unix shell syntax, @samp{$} is the prefix to substitute an |
1818 |
variable value. |
environment variable value. If the input contains @samp{$$}, that is |
1819 |
|
converted to @samp{$}; this gives the user a way to ``quote'' a |
1820 |
|
@samp{$}. |
1821 |
|
|
1822 |
The environment variable name is the series of alphanumeric characters |
The environment variable name is the series of alphanumeric characters |
1823 |
(including underscores) that follow the @samp{$}. If the character following |
(including underscores) that follow the @samp{$}. If the character following |
1824 |
the @samp{$} is a @samp{@{}, then the variable name is everything up to the |
the @samp{$} is a @samp{@{}, then the variable name is everything up to the |
1825 |
matching @samp{@}}. |
matching @samp{@}}. |
1826 |
|
|
1827 |
|
Calling @code{substitute-in-file-name} on output produced by |
1828 |
|
@code{substitute-in-file-name} tends to give incorrect results. For |
1829 |
|
instance, use of @samp{$$} to quote a single @samp{$} won't work |
1830 |
|
properly, and @samp{$} in an environment variable's value could lead |
1831 |
|
to repeated substitution. Therefore, programs that call this function |
1832 |
|
and put the output where it will be passed to this function need to |
1833 |
|
double all @samp{$} characters to prevent subsequent incorrect |
1834 |
|
results. |
1835 |
|
|
1836 |
@c Wordy to avoid overfull hbox. --rjc 15mar92 |
@c Wordy to avoid overfull hbox. --rjc 15mar92 |
1837 |
Here we assume that the environment variable @code{HOME}, which holds |
Here we assume that the environment variable @code{HOME}, which holds |
1838 |
the user's home directory name, has value @samp{/xcssun/users/rms}. |
the user's home directory name, has value @samp{/xcssun/users/rms}. |
2299 |
The @var{handler} then needs to figure out whether to handle |
The @var{handler} then needs to figure out whether to handle |
2300 |
@var{filename} or @var{dirname}. |
@var{filename} or @var{dirname}. |
2301 |
|
|
2302 |
|
If the specified file name matches more than one handler, the one |
2303 |
|
whose match starts last in the file name gets precedence. This rule |
2304 |
|
is chosen so that handlers for jobs such as uncompression are handled |
2305 |
|
first, before handlers for jobs such as remote file access. |
2306 |
|
|
2307 |
Here are the operations that a magic file name handler gets to handle: |
Here are the operations that a magic file name handler gets to handle: |
2308 |
|
|
2309 |
@ifnottex |
@ifnottex |
2433 |
multiple handlers, and for operations that have two file names that may |
multiple handlers, and for operations that have two file names that may |
2434 |
each have handlers. |
each have handlers. |
2435 |
|
|
2436 |
|
@kindex safe-magic (@r{property}) |
2437 |
|
Handlers that don't really do anything specal for actual access to the |
2438 |
|
file---such as the ones that implement completion of host names for |
2439 |
|
remote file names---should have a non-@code{nil} @code{safe-magic} |
2440 |
|
property. For instance, Emacs normally ``protects'' directory names |
2441 |
|
it finds in @code{PATH} from becoming magic, if they look like magic |
2442 |
|
file names, by prefixing them with @samp{/:}. But if the handler that |
2443 |
|
would be used for them has a non-@code{nil} @code{safe-magic} |
2444 |
|
property, the @samp{/:} is not added. |
2445 |
|
|
2446 |
@defvar inhibit-file-name-handlers |
@defvar inhibit-file-name-handlers |
2447 |
This variable holds a list of handlers whose use is presently inhibited |
This variable holds a list of handlers whose use is presently inhibited |
2448 |
for a certain operation. |
for a certain operation. |
2461 |
@end defun |
@end defun |
2462 |
|
|
2463 |
@defun file-local-copy filename |
@defun file-local-copy filename |
2464 |
This function copies file @var{filename} to an ordinary non-magic file, |
This function copies file @var{filename} to an ordinary non-magic file |
2465 |
if it isn't one already. |
on the local machine, if it isn't on the local machine already. Magic |
2466 |
|
file names should handle the @code{file-local-copy} operation if they |
2467 |
If @var{filename} specifies a magic file name, which programs |
refer to files on other machines. A magic file name that is used for |
2468 |
outside Emacs cannot directly read or write, this copies the contents to |
other purposes than remote file access should not handle |
2469 |
an ordinary file and returns that file's name. |
@code{file-local-copy}; then this function will treat the file as |
2470 |
|
local. |
2471 |
If @var{filename} is an ordinary file name, not magic, then this function |
|
2472 |
does nothing and returns @code{nil}. |
If @var{filename} is local, whether magic or not, this function does |
2473 |
|
nothing and returns @code{nil}. Otherwise it returns the file name |
2474 |
|
of the local copy file. |
2475 |
|
@end defun |
2476 |
|
|
2477 |
|
@defun file-remote-p filename |
2478 |
|
This functions return @code{t} if @var{filename} is a remote file---that is, |
2479 |
|
a magic file name that handles @code{file-local-copy}. |
2480 |
@end defun |
@end defun |
2481 |
|
|
2482 |
@defun unhandled-file-name-directory filename |
@defun unhandled-file-name-directory filename |
2644 |
@code{buffer-file-format} for writing auto-save files. This variable is |
@code{buffer-file-format} for writing auto-save files. This variable is |
2645 |
always buffer-local in all buffers. |
always buffer-local in all buffers. |
2646 |
@end defvar |
@end defvar |
2647 |
|
|
2648 |
|
@ignore |
2649 |
|
arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c |
2650 |
|
@end ignore |