Render timing.c robust in the face of strangeness. The strangenesses

[u/mdw/putty] / doc / psftp.but

diff --git a/doc/psftp.but b/doc/psftp.but
index 57ba0fa..5cc26f0 100644 (file)
--- a/doc/psftp.but
+++ b/doc/psftp.but
@@ -1,4 +1,4 @@
-\versionid $Id: psftp.but,v 1.3 2001/12/16 13:33:04 simon Exp $
+\define{versionidpsftp} \versionid $Id$

 
 \C{psftp} Using PSFTP to transfer files securely
 
 
 \C{psftp} Using PSFTP to transfer files securely
 


@@ -8,8 +8,8 @@ securely between computers using an SSH connection.
 PSFTP differs from PSCP in the following ways:
 
 \b PSCP should work on virtually every SSH server. PSFTP uses the
 PSFTP differs from PSCP in the following ways:
 
 \b PSCP should work on virtually every SSH server. PSFTP uses the

-new SFTP protocol, which is a feature of SSH 2 only. (PSCP will also
-use this protocol if it can, but there is an SSH 1 equivalent it can
+new SFTP protocol, which is a feature of SSH-2 only. (PSCP will also
+use this protocol if it can, but there is an SSH-1 equivalent it can

 fall back to if it cannot.)
 
 \b PSFTP allows you to run an interactive file transfer session,
 fall back to if it cannot.)
 
 \b PSFTP allows you to run an interactive file transfer session,


@@ -49,45 +49,13 @@ any server:
 At this point you can type \c{open server.example.com} or \c{open
 fred@server.example.com} to start a session.
 
 At this point you can type \c{open server.example.com} or \c{open
 fred@server.example.com} to start a session.
 

-The following sections describe PSFTP's command-line options.
+PSFTP accepts all the general command line options supported by the
+PuTTY tools, except the ones which make no sense in a file transfer
+utility. See \k{using-general-opts} for a description of these
+options. (The ones not supported by PSFTP are clearly marked.)

 
 

-\S{psftp-option-l} \c{-l}: specify a user name
-
-The \c{-l} option is an alternative way to specify the user name to
-log in as, on the command line. Instead of typing \c{psftp
-user@host}, you can also type \c{psftp host -l user}.
-
-This option does not work in the \c{open} command once PSFTP has
-started.
-
-\S{psftp-option-P} \c{-P}: specify a port number
-
-If the \c{host} you specify is a saved session, PSFTP uses any port
-number specified in that saved session.  If not, PSFTP uses the
-default SSH port, 22.  The \c{-P} option allows you specify the port
-number to connect to for PSFTP's SSH connection.
-
-\S{psftp-option-v}\c{-v}: show verbose messages
-
-The \c{-v} option to PSFTP makes it print verbose information about
-the establishing of the SSH connection. The information displayed is
-equivalent to what is shown in the PuTTY Event Log
-(\k{using-eventlog}).
-
-This information may be useful for debugging problems with PSFTP.
-
-\S{psftp-option-pw} \c{-pw}: specify a password
-
-If a password is required to connect to the \c{host}, PSFTP will
-interactively prompt you for it.  However, this may not always be
-appropriate.  If you are running PSFTP as part of some automated
-job, it will not be possible to enter a password by hand.  The
-\c{-pw} option to PSFTP lets you specify the password to use on the
-command line.
-
-Since specifying passwords in scripts is a bad idea for security
-reasons, you might want instead to consider using public-key
-authentication; see \k{psftp-pubkey}.
+PSFTP also supports some of its own options. The following sections
+describe PSFTP's specific command-line options.

 
 \S{psftp-option-b} \c{-b}: specify a file containing batch commands
 
 
 \S{psftp-option-b} \c{-b}: specify a file containing batch commands
 


@@ -114,15 +82,16 @@ and then you could run the script by typing
 
 When you run a batch script in this way, PSFTP will abort the script
 if any command fails to complete successfully. To change this
 
 When you run a batch script in this way, PSFTP will abort the script
 if any command fails to complete successfully. To change this

-behaviour, you can use the \c{-be} option (\k{psftp-option-be}).
+behaviour, you can add the \c{-be} option (\k{psftp-option-be}).

 
 \S{psftp-option-bc} \c{-bc}: display batch commands as they are run
 
 The \c{-bc} option alters what PSFTP displays while processing a
 
 \S{psftp-option-bc} \c{-bc}: display batch commands as they are run
 
 The \c{-bc} option alters what PSFTP displays while processing a

-batch script. With the \c{-bc} option, PSFTP will display prompts
-and commands just as if the commands had been typed at the keyboard.
-So instead of seeing this:
+batch script specified with \c{-b}. With the \c{-bc} option, PSFTP
+will display prompts and commands just as if the commands had been
+typed at the keyboard. So instead of seeing this:

 
 

+\c C:\>psftp fred@hostname -b batchfile

 \c Sent username "fred"
 \c Remote working directory is /home/fred
 \c Listing directory /home/fred/lib
 \c Sent username "fred"
 \c Remote working directory is /home/fred
 \c Listing directory /home/fred/lib


@@ -134,6 +103,7 @@ So instead of seeing this:
 
 you might see this:
 
 
 you might see this:
 

+\c C:\>psftp fred@hostname -bc -b batchfile

 \c Sent username "fred"
 \c Remote working directory is /home/fred
 \c psftp> dir lib
 \c Sent username "fred"
 \c Remote working directory is /home/fred
 \c psftp> dir lib


@@ -147,12 +117,24 @@ you might see this:
 
 \S{psftp-option-be} \c{-be}: continue batch processing on errors
 
 
 \S{psftp-option-be} \c{-be}: continue batch processing on errors
 

-When running a batch file, this option causes PSFTP to continue
-processing even if a command fails to complete successfully.
+When running a batch file, this additional option causes PSFTP to
+continue processing even if a command fails to complete successfully.

 
 You might want this to happen if you wanted to delete a file and
 didn't care if it was already not present, for example.
 
 
 You might want this to happen if you wanted to delete a file and
 didn't care if it was already not present, for example.
 

+\S{psftp-usage-options-batch}\c{-batch}: avoid interactive prompts
+
+If you use the \c{-batch} option, PSFTP will never give an
+interactive prompt while establishing the connection. If the
+server's host key is invalid, for example (see \k{gs-hostkey}), then
+the connection will simply be abandoned instead of asking you what
+to do next.
+
+This may help PSFTP's behaviour when it is used in automated
+scripts: using \c{-batch}, if something goes wrong at connection
+time, the batch job will fail rather than hang.
+

 \H{psftp-commands} Running PSFTP
 
 Once you have started your PSFTP session, you will see a \c{psftp>}
 \H{psftp-commands} Running PSFTP
 
 Once you have started your PSFTP session, you will see a \c{psftp>}


@@ -193,6 +175,48 @@ file whose name is \c{a file with "quotes" in it}.
 which passes its command line straight to Windows without splitting
 it up into words at all. See \k{psftp-cmd-pling}.)
 
 which passes its command line straight to Windows without splitting
 it up into words at all. See \k{psftp-cmd-pling}.)
 

+\S{psftp-wildcards} Wildcards in PSFTP
+
+Several commands in PSFTP support \q{wildcards} to select multiple
+files.
+
+For \e{local} file specifications (such as the first argument to
+\c{put}), wildcard rules for the local operating system are used. For
+instance, PSFTP running on Windows might require the use of \c{*.*}
+where PSFTP on Unix would need \c{*}.
+
+For \e{remote} file specifications (such as the first argument to
+\c{get}), PSFTP uses a standard wildcard syntax (similar to POSIX
+wildcards):
+
+\b \c{*} matches any sequence of characters (including a zero-length
+sequence).
+
+\b \c{?} matches exactly one character.
+
+\b \c{[abc]} matches exactly one character which can be \cw{a},
+\cw{b}, or \cw{c}.
+
+\lcont{
+
+\c{[a-z]} matches any character in the range \cw{a} to \cw{z}.
+
+\c{[^abc]} matches a single character that is \e{not} \cw{a}, \cw{b},
+or \cw{c}.
+
+Special cases: \c{[-a]} matches a literal hyphen (\cw{-}) or \cw{a};
+\c{[^-a]} matches all other characters. \c{[a^]} matches a literal
+caret (\cw{^}) or \cw{a}.
+
+}
+
+\b \c{\\} (backslash) before any of the above characters (or itself)
+removes that character's special meaning.
+
+A leading period (\cw{.}) on a filename is not treated specially,
+unlike in some Unix contexts; \c{get *} will fetch all files, whether
+or not they start with a leading period.
+

 \S{psftp-cmd-open} The \c{open} command: start a session
 
 If you started PSFTP by double-clicking in the GUI, or just by
 \S{psftp-cmd-open} The \c{open} command: start a session
 
 If you started PSFTP by double-clicking in the GUI, or just by


@@ -211,12 +235,19 @@ not opened successfully, PSFTP will terminate immediately.
 \S{psftp-cmd-quit} The \c{quit} command: end your session
 
 When you have finished your session, type the command \c{quit} to
 \S{psftp-cmd-quit} The \c{quit} command: end your session
 
 When you have finished your session, type the command \c{quit} to

-terminate PSFTP and return to the command line (or just close the
-PSFTP console window if you started it from the GUI).
+close the connection, terminate PSFTP and return to the command line
+(or just close the PSFTP console window if you started it from the
+GUI).

 
 You can also use the \c{bye} and \c{exit} commands, which have
 exactly the same effect.
 
 
 You can also use the \c{bye} and \c{exit} commands, which have
 exactly the same effect.
 

+\S{psftp-cmd-close} The \c{close} command: close your connection
+
+If you just want to close the network connection but keep PSFTP
+running, you can use the \c{close} command. You can then use the
+\c{open} command to open a new connection.
+

 \S{psftp-cmd-help} The \c{help} command: get quick online help
 
 If you type \c{help}, PSFTP will give a short list of the available
 \S{psftp-cmd-help} The \c{help} command: get quick online help
 
 If you type \c{help}, PSFTP will give a short list of the available


@@ -235,8 +266,12 @@ operate on. For example, if you type \c{get filename.dat} then PSFTP
 will look for \c{filename.dat} in your remote working directory on
 the server.
 
 will look for \c{filename.dat} in your remote working directory on
 the server.
 

-To change your remote working directory, use the \c{cd} command. To
-display your current remote working directory, type \c{pwd}.
+To change your remote working directory, use the \c{cd} command. If
+you don't provide an argument, \c{cd} will return you to your home
+directory on the server (more precisely, the remote directory you were
+in at the start of the connection).
+
+To display your current remote working directory, type \c{pwd}.

 
 \S{psftp-cmd-lcd} The \c{lcd} and \c{lpwd} commands: changing the
 local working directory
 
 \S{psftp-cmd-lcd} The \c{lcd} and \c{lpwd} commands: changing the
 local working directory


@@ -268,6 +303,17 @@ specify the local file name after the remote one:
 This will fetch the file on the server called \c{myfile.dat}, but
 will save it to your local machine under the name \c{newname.dat}.
 
 This will fetch the file on the server called \c{myfile.dat}, but
 will save it to your local machine under the name \c{newname.dat}.
 

+To fetch an entire directory recursively, you can use the \c{-r}
+option:
+
+\c get -r mydir
+\c get -r mydir newname
+
+(If you want to fetch a file whose name starts with a hyphen, you
+may have to use the \c{--} special argument, which stops \c{get}
+from interpreting anything as a switch after it. For example,
+\cq{get -- -silly-name-}.)
+

 \S{psftp-cmd-put} The \c{put} command: send a file to the server
 
 To upload a file to the server from your local PC, you use the
 \S{psftp-cmd-put} The \c{put} command: send a file to the server
 
 To upload a file to the server from your local PC, you use the


@@ -285,6 +331,40 @@ specify the remote file name after the local one:
 This will send the local file called \c{myfile.dat}, but will store
 it on the server under the name \c{newname.dat}.
 
 This will send the local file called \c{myfile.dat}, but will store
 it on the server under the name \c{newname.dat}.
 

+To send an entire directory recursively, you can use the \c{-r}
+option:
+
+\c put -r mydir
+\c put -r mydir newname
+
+(If you want to send a file whose name starts with a hyphen, you may
+have to use the \c{--} special argument, which stops \c{put} from
+interpreting anything as a switch after it. For example, \cq{put --
+-silly-name-}.)
+
+\S{psftp-cmd-mgetput} The \c{mget} and \c{mput} commands: fetch or
+send multiple files
+
+\c{mget} works almost exactly like \c{get}, except that it allows
+you to specify more than one file to fetch at once. You can do this
+in two ways:
+
+\b by giving two or more explicit file names (\cq{mget file1.txt
+file2.txt})
+
+\b by using a wildcard (\cq{mget *.txt}).
+
+Every argument to \c{mget} is treated as the name of a file to fetch
+(unlike \c{get}, which will interpret at most one argument like
+that, and a second argument will be treated as an alternative name
+under which to store the retrieved file), or a wildcard expression
+matching more than one file.
+
+The \c{-r} and \c{--} options from \c{get} are also available with
+\c{mget}.
+
+\c{mput} is similar to \c{put}, with the same differences.
+

 \S{psftp-cmd-regetput} The \c{reget} and \c{reput} commands:
 resuming file transfers
 
 \S{psftp-cmd-regetput} The \c{reget} and \c{reput} commands:
 resuming file transfers
 


@@ -300,6 +380,13 @@ syntax of \c{get} and \c{put}:
 
 \c reget myfile.dat
 \c reget myfile.dat newname.dat
 
 \c reget myfile.dat
 \c reget myfile.dat newname.dat

+\c reget -r mydir
+
+These commands are intended mainly for resuming interrupted transfers.
+They assume that the remote file or directory structure has not
+changed in any way; if there have been changes, you may end up with
+corrupted files. In particular, the \c{-r} option will not pick up
+changes to files or directories already transferred in full.

 
 \S{psftp-cmd-dir} The \c{dir} command: list remote files
 
 
 \S{psftp-cmd-dir} The \c{dir} command: list remote files
 


@@ -312,22 +399,28 @@ You can also list the contents of a different directory by typing
 \c dir /home/fred
 \c dir sources
 
 \c dir /home/fred
 \c dir sources
 

+And you can list a subset of the contents of a directory by
+providing a wildcard:
+
+\c dir /home/fred/*.txt
+\c dir sources/*.c
+

 The \c{ls} command works exactly the same way as \c{dir}.
 
 \S{psftp-cmd-chmod} The \c{chmod} command: change permissions on
 remote files
 
 The \c{ls} command works exactly the same way as \c{dir}.
 
 \S{psftp-cmd-chmod} The \c{chmod} command: change permissions on
 remote files
 

-PSFTP allows you to modify the file permissions on files on the
-server. You do this using the \c{chmod} command, which works very
-much like the Unix \c{chmod} command.
+PSFTP allows you to modify the file permissions on files and
+directories on the server. You do this using the \c{chmod} command,
+which works very much like the Unix \c{chmod} command.

 
 The basic syntax is \c{chmod modes file}, where \c{modes} represents
 a modification to the file permissions, and \c{file} is the filename
 
 The basic syntax is \c{chmod modes file}, where \c{modes} represents
 a modification to the file permissions, and \c{file} is the filename

-to modify. For example:
+to modify. You can specify multiple files or wildcards. For example:

 
 \c chmod go-rwx,u+w privatefile
 
 \c chmod go-rwx,u+w privatefile

-\c chmod a+r publicfile
-\c chmod 640 groupfile
+\c chmod a+r public*
+\c chmod 640 groupfile1 groupfile2

 
 The \c{modes} parameter can be a set of octal digits in the Unix
 style. (If you don't know what this means, you probably don't want
 
 The \c{modes} parameter can be a set of octal digits in the Unix
 style. (If you don't know what this means, you probably don't want


@@ -354,7 +447,8 @@ permissions for members of the owning group and everybody else (so
 the only permissions left are the ones for the file owner). \c{u+w}
 adds write permission for the file owner.
 
 the only permissions left are the ones for the file owner). \c{u+w}
 adds write permission for the file owner.
 

-\b The second example: \c{a+r} adds read permission for everybody.
+\b The second example: \c{a+r} adds read permission for everybody to
+all files and directories starting with \q{public}.

 
 In addition to all this, there are a few extra special cases for
 Unix systems. On non-Unix systems these are unlikely to be useful:
 
 In addition to all this, there are a few extra special cases for
 Unix systems. On non-Unix systems these are unlikely to be useful:


@@ -376,9 +470,18 @@ normally only the owner of the \e{directory} would be allowed to).
 
 \S{psftp-cmd-del} The \c{del} command: delete remote files
 
 
 \S{psftp-cmd-del} The \c{del} command: delete remote files
 

-To delete a file on the server, type \c{del} and then the filename:
+To delete a file on the server, type \c{del} and then the filename
+or filenames:

 
 \c del oldfile.dat
 
 \c del oldfile.dat

+\c del file1.txt file2.txt
+\c del *.o
+
+Files will be deleted without further prompting, even if multiple files
+are specified.
+
+\c{del} will only delete files. You cannot use it to delete
+directories; use \c{rmdir} for that.

 
 The \c{rm} command works exactly the same way as \c{del}.
 
 
 The \c{rm} command works exactly the same way as \c{del}.
 


@@ -389,26 +492,47 @@ directory name:
 
 \c mkdir newstuff
 
 
 \c mkdir newstuff
 

+You can specify multiple directories to create at once:
+
+\c mkdir dir1 dir2 dir3
+

 \S{psftp-cmd-rmdir} The \c{rmdir} command: remove remote directories
 
 To remove a directory on the server, type \c{rmdir} and then the
 \S{psftp-cmd-rmdir} The \c{rmdir} command: remove remote directories
 
 To remove a directory on the server, type \c{rmdir} and then the

-directory name:
+directory name or names:

 
 \c rmdir oldstuff
 
 \c rmdir oldstuff

+\c rmdir *.old ancient
+
+Directories will be deleted without further prompting, even if
+multiple directories are specified.

 
 Most SFTP servers will probably refuse to remove a directory if the
 directory has anything in it, so you will need to delete the
 contents first.
 
 
 Most SFTP servers will probably refuse to remove a directory if the
 directory has anything in it, so you will need to delete the
 contents first.
 

-\S{psftp-cmd-ren} The \c{ren} command: rename remote files
+\S{psftp-cmd-mv} The \c{mv} command: move and rename remote files
+
+To rename a single file on the server, type \c{mv}, then the current
+file name, and then the new file name:
+
+\c mv oldfile newname

 
 

-To rename a file on the server, type \c{ren}, then the current file
-name, and then the new file name:
+You can also move the file into a different directory and change the
+name:

 
 

-\c ren oldfile newname
+\c mv oldfile dir/newname

 
 

-The \c{rename} and \c{mv} commands work exactly the same way as
-\c{ren}.
+To move one or more files into an existing subdirectory, specify the
+files (using wildcards if desired), and then the destination
+directory:
+
+\c mv file dir
+\c mv file1 dir1/file2 dir2
+\c mv *.c *.h ..
+
+The \c{rename} and \c{ren} commands work exactly the same way as
+\c{mv}.

 
 \S{psftp-cmd-pling} The \c{!} command: run a local Windows command
 
 
 \S{psftp-cmd-pling} The \c{!} command: run a local Windows command
 


@@ -429,7 +553,7 @@ using the Windows \c{ren} command to rename files on your local PC.
 \H{psftp-pubkey} Using public key authentication with PSFTP
 
 Like PuTTY, PSFTP can authenticate using a public key instead of a
 \H{psftp-pubkey} Using public key authentication with PSFTP
 
 Like PuTTY, PSFTP can authenticate using a public key instead of a

-password. There are two ways you can do this.
+password. There are three ways you can do this.

 
 Firstly, PSFTP can use PuTTY saved sessions in place of hostnames.
 So you might do this:
 
 Firstly, PSFTP can use PuTTY saved sessions in place of hostnames.
 So you might do this:


@@ -443,7 +567,11 @@ username to log in as (see \k{config-username}).
 hostname: type \c{psftp sessionname}, where \c{sessionname} is
 replaced by the name of your saved session.
 
 hostname: type \c{psftp sessionname}, where \c{sessionname} is
 replaced by the name of your saved session.
 

-Secondly, PSFTP will attempt to authenticate using Pageant if Pageant
+Secondly, you can supply the name of a private key file on the command
+line, with the \c{-i} option. See \k{using-cmdline-identity} for more
+information.
+
+Thirdly, PSFTP will attempt to authenticate using Pageant if Pageant

 is running (see \k{pageant}). So you would do this:
 
 \b Ensure Pageant is running, and has your private key stored in it.
 is running (see \k{pageant}). So you would do this:
 
 \b Ensure Pageant is running, and has your private key stored in it.