;; tramp-loaddefs.el. Otherwise, there would be recursive autoloading.
;;;###tramp-autoload
(defsubst tramp-adb-file-name-p (filename)
- "Check if it's a filename for ADB."
+ "Check if it's a FILENAME for ADB."
(and (tramp-tramp-file-p filename)
(string= (tramp-file-name-method (tramp-dissect-file-name filename))
tramp-adb-method)))
(defun tramp-archive-run-real-handler (operation args)
"Invoke normal file name handler for OPERATION.
-First arg specifies the OPERATION, second arg is a list of arguments to
-pass to the OPERATION."
+First arg specifies the OPERATION, second arg ARGS is a list of
+arguments to pass to the OPERATION."
(let* ((inhibit-file-name-handlers
`(tramp-archive-file-name-handler
.
;;;###tramp-autoload
(defun tramp-archive-file-name-handler (operation &rest args)
"Invoke the file archive related OPERATION.
-First arg specifies the OPERATION, second arg is a list of arguments to
-pass to the OPERATION."
+First arg specifies the OPERATION, second arg ARGS is a list of
+arguments to pass to the OPERATION."
(if (not tramp-archive-enabled)
;; Unregister `tramp-archive-file-name-handler'.
(progn
(url-hexify-string (tramp-gvfs-url-file-name archive)))
(defun tramp-archive-dissect-file-name (name)
- "Return a `tramp-file-name' structure.
+ "Return a `tramp-file-name' structure for NAME.
The structure consists of the `tramp-archive-method' method, the
hexified archive name as host, and the localname. The archive
name is kept in slot `hop'"
(tramp-file-name-hop vec)))
(defmacro with-parsed-tramp-archive-file-name (filename var &rest body)
- "Parse an archive filename and make components available in the body.
+ "Parse an archive filename and make components available in the BODY.
This works exactly as `with-parsed-tramp-file-name' for the Tramp
file name structure returned by `tramp-archive-dissect-file-name'.
A variable `foo-archive' (or `archive') will be bound to the
,@body)))
(defun tramp-archive-gvfs-file-name (name)
- "Return FILENAME in GVFS syntax."
+ "Return NAME in GVFS syntax."
(tramp-make-tramp-file-name
(tramp-archive-dissect-file-name name) nil 'nohop))
;; File name primitives.
(defun tramp-archive-handle-access-file (filename string)
- "Like `access-file' for Tramp files."
+ "Like `access-file' for file archives."
(access-file (tramp-archive-gvfs-file-name filename) string))
(defun tramp-archive-handle-copy-file
;; An implementation of information caching for remote files.
;; Each connection, identified by a `tramp-file-name' structure or by
-;; a process, has a unique cache. We distinguish 4 kind of caches,
+;; a process, has a unique cache. We distinguish 4 kind of caches,
;; depending on the key:
;;
;; - localname is NIL. This are reusable properties. Examples:
"*debug tramp" (mapcar #'list (mapcar #'buffer-name (buffer-list))))))
(defun tramp-list-remote-buffers ()
- "Return a list of all buffers with remote default-directory."
+ "Return a list of all buffers with remote `default-directory'."
(delq
nil
(mapcar
;; In Emacs 24 and 25, `tramp-unload-file-name-handlers' is not
;; autoloaded. So we declare it here in order to avoid recursive
;; load. This will be overwritten in tramp.el.
-(defun tramp-unload-file-name-handlers ())
+(defun tramp-unload-file-name-handlers () ".")
(require 'auth-source)
(require 'format-spec)
;; changed argument list, there are compiler warnings. We want to
;; avoid them in cases we know what we do.
(defmacro tramp-compat-funcall (function &rest arguments)
- "Call FUNCTION if it exists. Do not raise compiler warnings."
+ "Call FUNCTION with ARGUMENTS if it exists. Do not raise compiler warnings."
`(when (functionp ,function)
(with-no-warnings (funcall ,function ,@arguments))))
;; `cl-struct-slot-info' has been introduced with Emacs 25.
(defmacro tramp-compat-tramp-file-name-slots ()
+ "Return a list of slot names."
(if (fboundp 'cl-struct-slot-info)
'(cdr (mapcar #'car (cl-struct-slot-info 'tramp-file-name)))
'(cdr (mapcar #'car (get 'tramp-file-name 'cl-struct-slots)))))
;;;###tramp-autoload
(defun tramp-ftp-file-name-handler (operation &rest args)
- "Invoke the Ange-FTP handler for OPERATION.
+ "Invoke the Ange-FTP handler for OPERATION and ARGS.
First arg specifies the OPERATION, second arg is a list of arguments to
pass to the OPERATION."
(save-match-data
;; tramp-loaddefs.el. Otherwise, there would be recursive autoloading.
;;;###tramp-autoload
(defsubst tramp-ftp-file-name-p (filename)
- "Check if it's a filename that should be forwarded to Ange-FTP."
+ "Check if it's a FILENAME that should be forwarded to Ange-FTP."
(and (tramp-tramp-file-p filename)
(string= (tramp-file-name-method (tramp-dissect-file-name filename))
tramp-ftp-method)))
;; tramp-loaddefs.el. Otherwise, there would be recursive autoloading.
;;;###tramp-autoload
(defsubst tramp-gvfs-file-name-p (filename)
- "Check if it's a filename handled by the GVFS daemon."
+ "Check if it's a FILENAME handled by the GVFS daemon."
(and (tramp-tramp-file-p filename)
(let ((method
(tramp-file-name-method (tramp-dissect-file-name filename))))
;;;###tramp-autoload
(defun tramp-gvfs-file-name-handler (operation &rest args)
- "Invoke the GVFS related OPERATION.
+ "Invoke the GVFS related OPERATION and ARGS.
First arg specifies the OPERATION, second arg is a list of arguments to
pass to the OPERATION."
(unless tramp-gvfs-enabled
(butlast byte-array) byte-array)))))
(defun tramp-gvfs-stringify-dbus-message (message)
- "Convert a D-Bus message into readable UTF8 strings, used for traces."
+ "Convert a D-Bus MESSAGE into readable UTF8 strings, used for traces."
(cond
((and (consp message) (characterp (car message)))
(format "%S" (tramp-gvfs-dbus-byte-array-to-string message)))
(defun tramp-gvfs-monitor-process-filter (proc string)
"Read output from \"gvfs-monitor-file\" and add corresponding \
-file-notify events."
+`file-notify' events."
(let* ((events (process-get proc 'events))
(rest-string (process-get proc 'rest-string))
(dd (with-current-buffer (process-buffer proc) default-directory))
result))))
(defun tramp-gvfs-handler-mounted-unmounted (mount-info)
- "Signal handler for the \"org.gtk.vfs.MountTracker.mounted\" and
+ "Signal handler for the \"org.gtk.vfs.MountTracker.mounted\" and \
\"org.gtk.vfs.MountTracker.unmounted\" signals."
(ignore-errors
(let ((signal-name (dbus-event-member-name last-input-event))
#'tramp-rfn-eshadow-setup-minibuffer)))
(defun tramp-rfn-eshadow-update-overlay-regexp ()
+ "An overlay covering the shadowed part of the filename."
(format "[^%s/~]*\\(/\\|~\\)" tramp-postfix-host-format))
;; Package rfn-eshadow is preloaded in Emacs, but for some reason,
;; tramp-loaddefs.el. Otherwise, there would be recursive autoloading.
;;;###tramp-autoload
(defsubst tramp-rclone-file-name-p (filename)
- "Check if it's a filename for rclone."
+ "Check if it's a FILENAME for rclone."
(and (tramp-tramp-file-p filename)
(string= (tramp-file-name-method (tramp-dissect-file-name filename))
tramp-rclone-method)))
;;;###tramp-autoload
(defun tramp-rclone-file-name-handler (operation &rest args)
- "Invoke the rclone handler for OPERATION.
+ "Invoke the rclone handler for OPERATION and ARGS.
First arg specifies the OPERATION, second arg is a list of arguments to
pass to the OPERATION."
(let ((fn (assoc operation tramp-rclone-file-name-handler-alist)))
vec "gid-string" (tramp-get-local-gid 'string)))
(defun tramp-rclone-send-command (vec &rest args)
- "Send the COMMAND to connection VEC."
+ "Send a command to connection VEC.
+The command is the list of strings ARGS."
(with-current-buffer (tramp-get-connection-buffer vec)
(erase-buffer)
(let ((flags (tramp-get-method-parameter
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
+;;; Commentary:
+
+;; The file name handler implementation for ssh-alike remote connections.
+
;;; Code:
(eval-when-compile (require 'cl-lib))
(tramp-do-file-attributes-with-ls v localname id-format))))))))
(defun tramp-sh--quoting-style-options (vec)
+ "Quoting style options to be used for VEC."
(or
(tramp-get-ls-command-with
vec "--quoting-style=literal --show-control-chars")
p))))
(defun tramp-sh-gio-monitor-process-filter (proc string)
- "Read output from \"gio monitor\" and add corresponding file-notify events."
+ "Read output from \"gio monitor\" and add corresponding `file-notify' events."
(let ((events (process-get proc 'events))
(remote-prefix
(with-current-buffer (process-buffer proc)
(defun tramp-sh-gvfs-monitor-dir-process-filter (proc string)
"Read output from \"gvfs-monitor-dir\" and add corresponding \
-file-notify events."
+`file-notify' events."
(let ((events (process-get proc 'events))
(remote-prefix
(with-current-buffer (process-buffer proc)
(process-put proc 'rest-string string)))
(defun tramp-sh-inotifywait-process-filter (proc string)
- "Read output from \"inotifywait\" and add corresponding file-notify events."
+ "Read output from \"inotifywait\" and add corresponding `file-notify' events."
(let ((events (process-get proc 'events)))
(tramp-message proc 6 "%S\n%s" proc string)
(dolist (line (split-string string "[\n\r]+" 'omit))
(defun tramp-find-executable
(vec progname dirlist &optional ignore-tilde ignore-path)
- "Searches for PROGNAME in $PATH and all directories mentioned in DIRLIST.
+ "Search for PROGNAME in $PATH and all directories mentioned in DIRLIST.
First arg VEC specifies the connection, PROGNAME is the program
to search for, and DIRLIST gives the list of directories to
search. If IGNORE-TILDE is non-nil, directory names starting
-with `~' will be ignored. If IGNORE-PATH is non-nil, searches
+with `~' will be ignored. If IGNORE-PATH is non-nil, searches
only in DIRLIST.
Returns the absolute file name of PROGNAME, if found, and nil otherwise.
;; send it. This is likely not due to PATH_MAX, but PIPE_BUF. We
;; check it, and use a temporary file in case of. See Bug#33781.
(defun tramp-set-remote-path (vec)
- "Sets the remote environment PATH to existing directories.
+ "Set the remote environment PATH to existing directories.
I.e., for each directory in `tramp-remote-path', it is tested
whether it exists and if so, it is added to the environment
variable PATH."
extra-args))
(defun tramp-open-shell (vec shell)
- "Opens shell SHELL."
+ "Open shell SHELL."
(with-tramp-progress-reporter
vec 5 (format-message "Opening remote shell `%s'" shell)
;; Find arguments for this shell.
(tramp-get-connection-process vec) "remote-shell" shell)))
(defun tramp-find-shell (vec)
- "Opens a shell on the remote host which groks tilde expansion."
+ "Open a shell on the remote host which groks tilde expansion."
(with-current-buffer (tramp-get-buffer vec)
(let ((default-shell (tramp-get-method-parameter vec 'tramp-remote-shell))
shell)
(defun tramp-send-command-and-check
(vec command &optional subshell dont-suppress-err)
"Run COMMAND and check its exit status.
-Sends `echo $?' along with the COMMAND for checking the exit status.
-If COMMAND is nil, just sends `echo $?'. Returns t if the exit
+Send `echo $?' along with the COMMAND for checking the exit status.
+If COMMAND is nil, just send `echo $?'. Return t if the exit
status is 0, and nil otherwise.
If the optional argument SUBSHELL is non-nil, the command is
attr))
(defun tramp-shell-case-fold (string)
- "Converts STRING to shell glob pattern which ignores case."
+ "Convert STRING to shell glob pattern which ignores case."
(mapconcat
(lambda (c)
(if (equal (downcase c) (upcase c))
;; Variables local to connection.
(defun tramp-get-remote-path (vec)
- "Compile list of remote directories for $PATH.
+ "Compile list of remote directories for PATH.
Nonexistent directories are removed from spec."
(with-current-buffer (tramp-get-connection-buffer vec)
;; Expand connection-local variables.
;; tramp-loaddefs.el. Otherwise, there would be recursive autoloading.
;;;###tramp-autoload
(defsubst tramp-smb-file-name-p (filename)
- "Check if it's a filename for SMB servers."
+ "Check if it's a FILENAME for SMB servers."
(and (tramp-tramp-file-p filename)
(string= (tramp-file-name-method (tramp-dissect-file-name filename))
tramp-smb-method)))
;;;###tramp-autoload
(defun tramp-smb-file-name-handler (operation &rest args)
- "Invoke the SMB related OPERATION.
+ "Invoke the SMB related OPERATION and ARGS.
First arg specifies the OPERATION, second arg is a list of arguments to
pass to the OPERATION."
(let ((fn (assoc operation tramp-smb-file-name-handler-alist)))
device)))))))) ;11 file system number
(defun tramp-smb-do-file-attributes-with-stat (vec &optional id-format)
- "Implement `file-attributes' for Tramp files using stat command."
+ "Implement `file-attributes' for Tramp files using `stat' command."
(tramp-message
vec 5 "file attributes with stat: %s" (tramp-file-name-localname vec))
(let* (size id link uid gid atime mtime ctime mode inode)
(tramp-flush-connection-property v "process-buffer")))))
(defun tramp-smb-handle-substitute-in-file-name (filename)
- "Like `handle-substitute-in-file-name' for Tramp files.
+ "Like `substitute-in-file-name' for Tramp files.
\"//\" substitutes only in the local filename part. Catches
errors for shares like \"C$/\", which are common in Microsoft Windows."
;; Check, whether the local part is a quoted file name.
(buffer-substring (point) (point-at-eol)) nil 'omit)))))))))
(defun tramp-smb-get-stat-capability (vec)
- "Check whether the SMB server supports the STAT command."
+ "Check whether the SMB server supports the `stat' command."
;; When we are not logged in yet, we return nil.
(if (and (tramp-smb-get-share vec)
(process-live-p (tramp-get-connection-process vec)))
(tramp-smb-send-command vec "$rawui.WindowSize = $winsize"))
(defun tramp-smb-shell-quote-argument (s)
- "Similar to `shell-quote-argument', but uses windows cmd syntax."
+ "Similar to `shell-quote-argument', but uses Windows cmd syntax."
(let ((system-type 'ms-dos))
(tramp-unquote-shell-quote-argument s)))
;; tramp-loaddefs.el. Otherwise, there would be recursive autoloading.
;;;###tramp-autoload
(defsubst tramp-sudoedit-file-name-p (filename)
- "Check if it's a filename for SUDOEDIT."
+ "Check if it's a FILENAME for SUDOEDIT."
(and (tramp-tramp-file-p filename)
(string= (tramp-file-name-method (tramp-dissect-file-name filename))
tramp-sudoedit-method)))
;;;###tramp-autoload
(defun tramp-sudoedit-file-name-handler (operation &rest args)
- "Invoke the SUDOEDIT handler for OPERATION.
+ "Invoke the SUDOEDIT handler for OPERATION and ARGS.
First arg specifies the OPERATION, second arg is a list of arguments to
pass to the OPERATION."
(let ((fn (assoc operation tramp-sudoedit-file-name-handler-alist)))
;; Used in `tramp-sudoedit-sudo-actions'.
(defun tramp-sudoedit-action-sudo (proc vec)
- "Check, whether a sudo process has finished.
-Remove unneeded output."
+ "Check, whether a sudo process has finished. Remove unneeded output."
;; There might be pending output for the exit status.
(unless (process-live-p proc)
(while (tramp-accept-process-output proc 0))
(car args) (buffer-string)))))))
(defun tramp-sudoedit-send-command-string (vec &rest args)
- "Run command ARGS and return the output as astring."
+ "Run command ARGS and return the output as a string."
(when (apply #'tramp-sudoedit-send-command vec args)
(with-current-buffer (tramp-get-connection-buffer vec)
(tramp-message vec 6 "\n%s" (buffer-string))
is a local file name, the backup directory is prepended with Tramp file
name prefix \(method, user, host) of file.
-\(setq tramp-backup-directory-alist backup-directory-alist)
+ (setq tramp-backup-directory-alist backup-directory-alist)
gives the same backup policy for Tramp files on their hosts like the
policy for local files."
(defconst tramp-echoed-echo-mark-regexp
(format "%s\\(\b\\( \b\\)?\\)\\{%d\\}"
tramp-echo-mark-marker tramp-echo-mark-marker-length)
- "Regexp which matches `tramp-echo-mark' as it gets echoed by
+ "Regexp which matches `tramp-echo-mark' as it gets echoed by \
the remote shell.")
(defcustom tramp-local-end-of-line
(tramp-set-syntax 'tramp-syntax (tramp-compat-tramp-syntax)))
(defun tramp-syntax-values ()
- "Return possible values of `tramp-syntax', a list"
+ "Return possible values of `tramp-syntax', a list."
(let ((values (cdr (get 'tramp-syntax 'custom-type))))
(setq values (mapcar #'last values)
values (mapcar #'car values))
values))
(defun tramp-lookup-syntax (alist)
- "Look up a syntax string in ALIST according to `tramp-compat-tramp-syntax.'
+ "Look up a syntax string in ALIST according to `tramp-compat-tramp-syntax'.
Raise an error if `tramp-syntax' is invalid."
(or (cdr (assq (tramp-compat-tramp-syntax) alist))
(error "Wrong `tramp-syntax' %s" tramp-syntax)))
"Alist mapping Tramp syntax to strings beginning Tramp file names.")
(defun tramp-build-prefix-format ()
+ "Return `tramp-prefix-format' according to `tramp-syntax'."
(tramp-lookup-syntax tramp-prefix-format-alist))
(defvar tramp-prefix-format nil ;Initialized when defining `tramp-syntax'!
Used in `tramp-make-tramp-file-name'.")
(defun tramp-build-prefix-regexp ()
+ "Return `tramp-prefix-regexp'."
(concat "^" (regexp-quote tramp-prefix-format)))
(defvar tramp-prefix-regexp nil ;Initialized when defining `tramp-syntax'!
"Alist mapping Tramp syntax to regexps matching methods identifiers.")
(defun tramp-build-method-regexp ()
+ "Return `tramp-method-regexp' according to `tramp-syntax'."
(tramp-lookup-syntax tramp-method-regexp-alist))
(defvar tramp-method-regexp nil ;Initialized when defining `tramp-syntax'!
"Alist mapping Tramp syntax to the delimiter after the method.")
(defun tramp-build-postfix-method-format ()
+ "Return `tramp-postfix-method-format' according to `tramp-syntax'."
(tramp-lookup-syntax tramp-postfix-method-format-alist))
(defvar tramp-postfix-method-format nil ;Init'd when defining `tramp-syntax'!
Used in `tramp-make-tramp-file-name'.")
(defun tramp-build-postfix-method-regexp ()
+ "Return `tramp-postfix-method-regexp'."
(regexp-quote tramp-postfix-method-format))
(defvar tramp-postfix-method-regexp nil ;Init'd when defining `tramp-syntax'!
"Alist mapping Tramp syntax to strings prefixing IPv6 addresses.")
(defun tramp-build-prefix-ipv6-format ()
+ "Return `tramp-prefix-ipv6-format' according to `tramp-syntax'."
(tramp-lookup-syntax tramp-prefix-ipv6-format-alist))
(defvar tramp-prefix-ipv6-format nil ;Initialized when defining `tramp-syntax'!
Used in `tramp-make-tramp-file-name'.")
(defun tramp-build-prefix-ipv6-regexp ()
+ "Return `tramp-prefix-ipv6-regexp'."
(regexp-quote tramp-prefix-ipv6-format))
(defvar tramp-prefix-ipv6-regexp nil ;Initialized when defining `tramp-syntax'!
"Alist mapping Tramp syntax to suffix for IPv6 addresses.")
(defun tramp-build-postfix-ipv6-format ()
+ "Return `tramp-postfix-ipv6-format' according to `tramp-syntax'."
(tramp-lookup-syntax tramp-postfix-ipv6-format-alist))
(defvar tramp-postfix-ipv6-format nil ;Initialized when defining `tramp-syntax'!
Used in `tramp-make-tramp-file-name'.")
(defun tramp-build-postfix-ipv6-regexp ()
+ "Return `tramp-postfix-ipv6-regexp'."
(regexp-quote tramp-postfix-ipv6-format))
(defvar tramp-postfix-ipv6-regexp nil ;Initialized when defining `tramp-syntax'!
"Alist mapping Tramp syntax to strings between host and local names.")
(defun tramp-build-postfix-host-format ()
+ "Return `tramp-postfix-host-format' according to `tramp-syntax'."
(tramp-lookup-syntax tramp-postfix-host-format-alist))
(defvar tramp-postfix-host-format nil ;Initialized when defining `tramp-syntax'!
Used in `tramp-make-tramp-file-name'.")
(defun tramp-build-postfix-host-regexp ()
+ "Return `tramp-postfix-host-regexp'."
(regexp-quote tramp-postfix-host-format))
(defvar tramp-postfix-host-regexp nil ;Initialized when defining `tramp-syntax'!
"Regexp matching localnames.")
(defconst tramp-unknown-id-string "UNKNOWN"
- "String used to denote an unknown user or group")
+ "String used to denote an unknown user or group.")
(defconst tramp-unknown-id-integer -1
- "Integer used to denote an unknown user or group")
+ "Integer used to denote an unknown user or group.")
;;; File name format:
See also `tramp-file-name-regexp'.")
(defun tramp-build-file-name-regexp ()
+ "Return `tramp-file-name-regexp'."
(car tramp-file-name-structure))
;;;###autoload
"Alist mapping incomplete Tramp file names.")
(defun tramp-build-completion-file-name-regexp ()
+ "Return `tramp-completion-file-name-regexp' according to `tramp-syntax'."
(tramp-lookup-syntax tramp-completion-file-name-regexp-alist))
(defvar tramp-completion-file-name-regexp
In the Emacs normally running Tramp, evaluate the above code
\(replace \"xxx\" and \"yyy\" by the remote user and host name,
respectively). You can do this, for example, by pasting it into
-the `*scratch*' buffer and then hitting C-j with the cursor after the
+the `*scratch*' buffer and then hitting `C-j' with the cursor after the
last closing parenthesis. Note that it works only if you have configured
\"ssh\" to run without password query, see ssh-agent(1).
You will see the number of bytes sent successfully to the remote host.
If that number exceeds 1000, you can stop the execution by hitting
-C-g, because your Emacs is likely clean.
+`C-g', because your Emacs is likely clean.
When it is necessary to set `tramp-chunksize', you might consider to
use an out-of-the-band method \(like \"scp\") instead of an internal one
experiment a bit, e.g. changing the values of `init' and `step'
in the third line of the code.
-Please raise a bug report via \"M-x tramp-bug\" if your system needs
+Please raise a bug report via \\[tramp-bug] if your system needs
this variable to be set as well."
:type '(choice (const nil) integer))
t))
(defun tramp-find-method (method user host)
- "Return the right method string to use.
-This is METHOD, if non-nil. Otherwise, do a lookup in
+ "Return the right method string to use depending on USER and HOST.
+This is METHOD, if non-nil. Otherwise, do a lookup in
`tramp-default-method-alist' and `tramp-default-method'."
(when (and method
(or (string-equal method "")
(propertize result 'tramp-default t))))
(defun tramp-find-user (method user host)
- "Return the right user string to use.
-This is USER, if non-nil. Otherwise, do a lookup in
+ "Return the right user string to use depending on METHOD and HOST.
+This is USER, if non-nil. Otherwise, do a lookup in
`tramp-default-user-alist' and `tramp-default-user'."
(let ((result
(or user
(propertize result 'tramp-default t))))
(defun tramp-find-host (method user host)
- "Return the right host string to use.
-This is HOST, if non-nil. Otherwise, do a lookup in
+ "Return the right host string to use depending on METHOD and USER.
+This is HOST, if non-nil. Otherwise, do a lookup in
`tramp-default-host-alist' and `tramp-default-host'."
(let ((result
(or (and (> (length host) 0) host)
localname (file name on remote host), and hop.
Unless NODEFAULT is non-nil, method, user and host are expanded
-to their default values. For the other file name parts, no
+to their default values. For the other file name parts, no
default values are used."
(save-match-data
(unless (tramp-tramp-file-p name)
(when localname localname)))
(defun tramp-get-buffer (vec &optional dont-create)
- "Get the connection buffer to be used for VEC."
+ "Get the connection buffer to be used for VEC.
+Unless DONT-CREATE, the buffer is created when it doesn't exist yet."
(or (get-buffer (tramp-buffer-name vec))
(unless dont-create
(with-current-buffer (get-buffer-create (tramp-buffer-name vec))
(defun tramp-get-connection-buffer (vec &optional dont-create)
"Get the connection buffer to be used for VEC.
+Unless DONT-CREATE, the buffer is created when it doesn't exist yet.
In case a second asynchronous communication has been started, it is different
from `tramp-get-buffer'."
(or (tramp-get-connection-property vec "process-buffer" nil)
(current-buffer)))
(defsubst tramp-debug-message (vec fmt-string &rest arguments)
- "Append message to debug buffer.
+ "Append message to debug buffer of VEC.
Message is formatted with FMT-STRING as control string and the remaining
ARGUMENTS to actually emit the message (if applicable)."
(with-current-buffer (tramp-get-debug-buffer vec)
"Emit an error.
VEC-OR-PROC identifies the connection to use, SIGNAL is the
signal identifier to be raised, remaining arguments passed to
-`tramp-message'. Finally, signal SIGNAL is raised."
+`tramp-message'. Finally, signal SIGNAL is raised with
+FMT-STRING and ARGUMENTS."
(let (tramp-message-show-message signal-hook-function)
(tramp-backtrace vec-or-proc)
(unless arguments
(font-lock-add-keywords 'emacs-lisp-mode '("\\<with-tramp-file-property\\>"))
(defmacro with-tramp-connection-property (key property &rest body)
- "Check in Tramp for property PROPERTY, otherwise executes BODY and set."
+ "Check in Tramp for property PROPERTY, otherwise execute BODY and set."
`(let ((value (tramp-get-connection-property ,key ,property 'undef)))
(when (eq value 'undef)
;; We cannot pass ,@body as parameter to
(defun tramp-run-real-handler (operation args)
"Invoke normal file name handler for OPERATION.
-First arg specifies the OPERATION, second arg is a list of arguments to
-pass to the OPERATION."
+First arg specifies the OPERATION, second arg ARGS is a list of
+arguments to pass to the OPERATION."
(let* ((inhibit-file-name-handlers
`(tramp-file-name-handler
tramp-vc-file-name-handler
(with-current-buffer (process-buffer (nth 0 args))
default-directory)))
;; Unknown file primitive.
- (t (error "unknown file I/O primitive: %s" operation))))
+ (t (error "Unknown file I/O primitive: %s" operation))))
(defun tramp-find-foreign-file-name-handler (filename &optional _operation)
"Return foreign file name handler if exists."
;; Main function.
(defun tramp-file-name-handler (operation &rest args)
- "Invoke Tramp file name handler.
+ "Invoke Tramp file name handler for OPERATION and ARGS.
Fall back to normal file name handler if no Tramp file name handler exists."
(let ((filename (apply #'tramp-file-name-for-operation operation args))
;; `file-remote-p' is called for everything, even for symbolic
(tramp-run-real-handler operation args))))
(defun tramp-completion-file-name-handler (operation &rest args)
- "Invoke Tramp file name completion handler.
+ "Invoke Tramp file name completion handler for OPERATION and ARGS.
Falls back to normal file name handler if no Tramp file name handler exists."
(let ((fn (assoc operation tramp-completion-file-name-handler-alist)))
(if (and fn tramp-mode)
;; Method, host name and user name completion for a file.
(defun tramp-completion-handle-file-name-completion
(filename directory &optional predicate)
- "Like `file-name-completion' for Tramp files."
+ "Like `file-name-completion' for partial Tramp files."
;; Suppress eager completion on not connected hosts.
(let ((non-essential t))
(try-completion
;; "/x:y@""/[x/y@" "/x:y@z" "/[x/y@z" "/x:y@z:" "/[x/y@z]"
;;["x" "y" nil nil] ["x" "y" "z" nil] ["x" "y" "z" ""]
(defun tramp-completion-dissect-file-name (name)
- "Return a list of `tramp-file-name' structures.
+ "Return a list of `tramp-file-name' structures for NAME.
They are collected by `tramp-completion-dissect-file-name1'."
(let* ((x-nil "\\|\\(\\)")
(tramp-completion-ipv6-regexp
tramp-completion-file-name-structure6)))))
(defun tramp-completion-dissect-file-name1 (structure name)
- "Return a `tramp-file-name' structure matching STRUCTURE.
+ "Return a `tramp-file-name' structure for NAME matching STRUCTURE.
The structure consists of remote method, remote user,
remote host and localname (filename on remote host)."
(save-match-data
;; Localname manipulation functions that grok Tramp localnames...
(defun tramp-handle-file-name-as-directory (file)
- "Like `file-name-as-directory' but aware of Tramp files."
+ "Like `file-name-as-directory' for Tramp files."
;; `file-name-as-directory' would be sufficient except localname is
;; the empty string.
(let ((v (tramp-dissect-file-name file t)))
(try-completion filename hits-ignored-extensions))))
(defun tramp-handle-file-name-directory (file)
- "Like `file-name-directory' but aware of Tramp files."
+ "Like `file-name-directory' for Tramp files."
;; Everything except the last filename thing is the directory. We
;; cannot apply `with-parsed-tramp-file-name', because this expands
;; the remote file name parts.
'noloc))))
(defun tramp-handle-file-name-nondirectory (file)
- "Like `file-name-nondirectory' but aware of Tramp files."
+ "Like `file-name-nondirectory' for Tramp files."
(with-parsed-tramp-file-name file nil
(tramp-run-real-handler #'file-name-nondirectory (list localname))))
(string-equal (file-remote-p file1) (file-remote-p file2)))))
(defun tramp-mode-string-to-int (mode-string)
- "Convert a ten-letter `drwxrwxrwx'-style mode string into mode bits."
+ "Convert a ten-letter \"drwxrwxrwx\"-style MODE-STRING into mode bits."
(let* (case-fold-search
(mode-chars (string-to-vector mode-string))
(owner-read (aref mode-chars 1))
This is used to map a mode number to a permission string.")
(defun tramp-file-mode-from-int (mode)
- "Turn an integer representing a file mode into an ls(1)-like string."
+ "Turn an integer representing a file MODE into an ls(1)-like string."
(let ((type (cdr
(assoc (logand (ash mode -12) 15) tramp-file-mode-type-map)))
(user (logand (ash mode -6) 7))
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
+;;; Commentary:
+
+;; Convenience functions around the Tramp version. Partly generated
+;; during Tramp configuration.
+
;;; Code:
;; In the Tramp GIT, the version number is auto-frobbed from tramp.el,
;; You should have received a copy of the GNU General Public License
;; along with this program. If not, see `https://www.gnu.org/licenses/'.
+;;; Commentary:
+
+;; A testsuite for testing file archives.
+
;;; Code:
;; The `tramp-archive-testnn-*' tests correspond to the respective
(tramp-archive-cleanup-hash)))
(defun tramp-archive-test-all (&optional interactive)
- "Run all tests for \\[tramp-archive]."
+ "Run all tests for \\[tramp-archive].
+If INTERACTIVE is non-nil, the tests are run interactively."
(interactive "p")
(funcall
(if interactive #'ert-run-tests-interactively #'ert-run-tests-batch)
(defun tramp--test-gvfs-p (&optional method)
"Check, whether the remote host runs a GVFS based method.
-This requires restrictions of file name syntax."
+This requires restrictions of file name syntax.
+If optional METHOD is given, it is checked first."
(or (member method tramp-gvfs-methods)
(tramp-gvfs-file-name-p tramp-test-temporary-file-directory)))
(defmacro tramp--test-with-proper-process-name-and-buffer (proc &rest body)
"Set \"process-name\" and \"process-buffer\" connection properties.
+The values are derived from PROC. Run BODY.
This is needed in timer functions as well as process filters and sentinels."
(declare (indent 1) (debug (processp body)))
`(let* ((v (tramp-get-connection-property ,proc "vector" nil))
(ert-fail (format "Hook `%s' still contains Tramp function" x))))))
(defun tramp-test-all (&optional interactive)
- "Run all tests for \\[tramp]."
+ "Run all tests for \\[tramp].
+If INTERACTIVE is non-nil, the tests are run interactively."
(interactive "p")
(funcall
(if interactive
projects / emacs.git / commitdiff