diff options
| -rw-r--r-- | doc/emacs/cmdargs.texi | 2 | ||||
| -rw-r--r-- | doc/lispref/files.texi | 31 | ||||
| -rw-r--r-- | doc/lispref/processes.texi | 11 | ||||
| -rw-r--r-- | lisp/eshell/esh-proc.el | 1 | ||||
| -rw-r--r-- | lisp/files.el | 5 | ||||
| -rw-r--r-- | lisp/simple.el | 16 |
6 files changed, 47 insertions, 19 deletions
diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index 960398df081..61ca827b00d 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -1034,7 +1034,7 @@ specifies a window 164 columns wide, enough for two ordinary width windows side by side, and 55 lines tall. The default frame width is 80 characters and the default height is -40 lines. You can omit either the width or the height or both. If +36 lines. You can omit either the width or the height or both. If you start the geometry with an integer, Emacs interprets it as the width. If you start with an @samp{x} followed by an integer, Emacs interprets it as the height. Thus, @samp{81} specifies just the diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index d929978b6ea..21823c95694 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -2512,9 +2512,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 @@ -2693,8 +2693,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 @@ -3385,11 +3385,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 diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 88b0382b7d1..13544298b6e 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -459,7 +459,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 @@ -842,7 +844,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 name handler, it might not be possible to apply @code{process-filter} or @code{process-sentinel} to diff --git a/lisp/eshell/esh-proc.el b/lisp/eshell/esh-proc.el index 3735f30c304..384846c7a3c 100644 --- a/lisp/eshell/esh-proc.el +++ b/lisp/eshell/esh-proc.el @@ -282,7 +282,6 @@ See `eshell-needs-pipe'." (let ((process-connection-type (unless (eshell-needs-pipe-p command) process-connection-type)) - ;; `start-process' can't deal with relative filenames. (command (file-local-name (expand-file-name command)))) (apply 'start-file-process (file-name-nondirectory command) nil command args))) diff --git a/lisp/files.el b/lisp/files.el index fb09c96c47e..0dd597efe11 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -1173,7 +1173,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)) diff --git a/lisp/simple.el b/lisp/simple.el index 0281464c61f..241f5ece3d0 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -3892,11 +3892,14 @@ interactively, this is t." (shell-command command t)))) (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 name 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 @@ -3941,12 +3944,15 @@ Similar to `start-process', but may invoke a file name 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 name handler invocation. File name handlers might not -support pty association, if PROGRAM is nil." +objects of file name handler invocation, so they need to be obtained +by calling `file-local-name', in case they are remote file names. + +File name 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)))) |