comparison lispref/files.texi @ 81762:44be65f35e43

* files.texi (Magic File Names): Introduce optional parameter CONNECTED for `file-remote-p'.

81761:c8bb24d5506d

If @var{filename} is local, whether magic or not, this function does
nothing and returns @code{nil}.  Otherwise it returns the file name
of the local copy file.
@end defun

@defun file-remote-p filename
This function tests whether @var{filename} is a remote file.  If
@var{filename} is local (not remote), the return value is @code{nil}.
If @var{filename} is indeed remote, the return value is a string that
identifies the remote system.

This identifier string can include a host name and a user name, as
well as characters designating the method used to access the remote
system.  For example, the remote identifier string for the filename
@code{/ssh:user@@host:/some/file} is @code{/ssh:user@@host:}.

If @code{file-remote-p} returns the same identifier for two different
filenames, that means they are stored on the same file system and can
be accessed locally with respect to each other.  This means, for
example, that it is possible to start a remote process accessing both
files at the same time.  Implementors of file handlers need to ensure
this principle is valid.
@end defun

@defun unhandled-file-name-directory filename
This function returns the name of a directory that is not magic.  It
uses the directory part of @var{filename} if that is not magic.  For a

81762:44be65f35e43

If @var{filename} is local, whether magic or not, this function does
nothing and returns @code{nil}.  Otherwise it returns the file name
of the local copy file.
@end defun

@defun file-remote-p filename &optional connected
This function tests whether @var{filename} is a remote file.  If
@var{filename} is local (not remote), the return value is @code{nil}.
If @var{filename} is indeed remote, the return value is a string that
identifies the remote system.

This identifier string can include a host name and a user name, as
well as characters designating the method used to access the remote
system.  For example, the remote identifier string for the filename
@code{/sudo::/some/file} is @code{/sudo:root@@localhost:}.

If @code{file-remote-p} returns the same identifier for two different
filenames, that means they are stored on the same file system and can
be accessed locally with respect to each other.  This means, for
example, that it is possible to start a remote process accessing both
files at the same time.  Implementors of file handlers need to ensure
this principle is valid.

The optional parameter @var{connected}, when passed non-@code{nil},
triggers an additional check whether the remote system has been
connected already.  The function returns then @code{nil} if there is
no corresponding open connection, even if @var{filename} is remote.
This can be used to avoid unnecessary connection attempts.
@end defun

@defun unhandled-file-name-directory filename
This function returns the name of a directory that is not magic.  It
uses the directory part of @var{filename} if that is not magic.  For a