Commit 2e8825d6 authored by Eli Zaretskii's avatar Eli Zaretskii

Improve documentation of 'file-local-name' and related APIs

* doc/lispref/files.texi (Unique File Names)
(Magic File Names, File Name Expansion): Improve documentation
of the "local part" of a remote file name.
* doc/lispref/processes.texi (Synchronous Processes)
(Asynchronous Processes): State explicitly that program and
file names passed to functions that start remote processes
need to be relative or obtained by 'file-local-name'.

* lisp/files.el (file-local-name):
* lisp/simple.el (start-file-process, process-file): Improve
the documentation of the "local part" of a remote file name,
and its use in APIs that start remote processes.
parent 11f0635c
Pipeline #400 failed with stage
in 6 seconds
......@@ -2519,9 +2519,9 @@ with @samp{/:}.
@defmac file-name-quote name
This macro adds the quotation prefix @samp{/:} to the file @var{name}.
For a local file @var{name}, it prefixes @var{name} with @samp{/:}.
If @var{name} is a remote file name, the local part of @var{name} is
quoted. If @var{name} is already a quoted file name, @var{name} is
returned unchanged.
If @var{name} is a remote file name, the local part of @var{name}
(@pxref{Magic File Names}) is quoted. If @var{name} is already a
quoted file name, @var{name} is returned unchanged.
@example
@group
......@@ -2700,8 +2700,8 @@ that remote host. If such a directory does not exist, or
@code{temporary-file-directory} is returned.
@end defun
In order to extract the local part of the path name from a temporary
file, @code{file-local-name} could be used.
In order to extract the local part of the file's name of a temporary
file, use @code{file-local-name} (@pxref{Magic File Names}).
@node File Name Completion
@subsection File Name Completion
......@@ -3382,11 +3382,24 @@ non-magic directory to serve as its current directory, and this function
is a good way to come up with one.
@end defun
@cindex local part of remote file name
@defun file-local-name filename
This function returns the local part of file @var{filename}. For a
remote @var{filename}, it returns a file name which could be used
directly as argument of a remote process. If @var{filename} is local,
this function returns the file name.
This function returns the @dfn{local part} of @var{filename}. This is
the part of the file's name that identifies it on the remote host, and
is typically obtained by removing from the remote file name the parts
that specify the remote host and the method of accessing it. For
example:
@smallexample
(file-local-name "/ssh:@var{user}@@@var{host}:/foo/bar")
@result{} "/foo/bar"
@end smallexample
For a remote @var{filename}, this function returns a file name which
could be used directly as an argument of a remote process
(@pxref{Asynchronous Processes}, and @pxref{Synchronous Processes}),
and as the program to run on the remote host. If @var{filename} is
local, this function returns it unchanged.
@end defun
@defopt remote-file-name-inhibit-cache
......
......@@ -451,7 +451,9 @@ present in @var{args}. To avoid confusion, it may be best to avoid
absolute file names in @var{args}, but rather to specify all file
names as relative to @code{default-directory}. The function
@code{file-relative-name} is useful for constructing such relative
file names.
file names. Alternatively, you can use @code{file-local-name}
(@pxref{Magic File Names}) to obtain an absolute file name as seen
from the remote host's perspective.
@end defun
@defvar process-file-side-effects
......@@ -817,7 +819,12 @@ In the latter case, the local part of @code{default-directory} becomes
the working directory of the process.
This function does not try to invoke file name handlers for
@var{program} or for the rest of @var{args}.
@var{program} or for the rest of @var{args}. For that reason, if
@var{program} or any of @var{args} use the remote-file syntax
(@pxref{Magic File Names}), they must be converted either to file
names relative to @code{default-directory}, or to names that identify
the files locally on the remote host, by running them through
@code{file-local-name}.
Depending on the implementation of the file handler, it might not be
possible to apply @code{process-filter} or @code{process-sentinel} to
......
......@@ -1150,7 +1150,10 @@ consecutive checks. For example:
(defun file-local-name (file)
"Return the local name component of FILE.
It returns a file name which can be used directly as argument of
This function removes from FILE the specification of the remote host
and the method of accessing the host, leaving only the part that
identifies FILE locally on the remote system.
The returned file name can be used directly as argument of
`process-file', `start-file-process', or `shell-command'."
(or (file-remote-p file 'localname) file))
......
......@@ -3866,11 +3866,14 @@ interactively, this is t."
(process-file shell-file-name nil t nil shell-command-switch command))))
(defun process-file (program &optional infile buffer display &rest args)
"Process files synchronously in a separate process.
"Process files synchronously in a separate process that runs PROGRAM.
Similar to `call-process', but may invoke a file handler based on
`default-directory'. The current working directory of the
subprocess is `default-directory'.
If PROGRAM is a remote file name, it should be processed
by `file-local-name' before passing it to this function.
File names in INFILE and BUFFER are handled normally, but file
names in ARGS should be relative to `default-directory', as they
are passed to the process verbatim. (This is a difference to
......@@ -3915,12 +3918,15 @@ Similar to `start-process', but may invoke a file handler based on
This handler ought to run PROGRAM, perhaps on the local host,
perhaps on a remote host that corresponds to `default-directory'.
In the latter case, the local part of `default-directory' becomes
the working directory of the process.
In the latter case, the local part of `default-directory', the one
produced from it by `file-local-name', becomes the working directory
of the process on the remote host.
PROGRAM and PROGRAM-ARGS might be file names. They are not
objects of file handler invocation. File handlers might not
support pty association, if PROGRAM is nil."
objects of file handler invocation, so they need to be obtained
by calling `file-local-name', in case they are remote file names.
File handlers might not support pty association, if PROGRAM is nil."
(let ((fh (find-file-name-handler default-directory 'start-file-process)))
(if fh (apply fh 'start-file-process name buffer program program-args)
(apply 'start-process name buffer program program-args))))
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment