draft-ietf-secsh-filexfer-02.txt

来自「OTP是开放电信平台的简称」· 文本 代码 · 共 1,628 行 · 第 1/4 页

   with the specified path exists, or if the specified directory is not
   empty, or if the path specified a file system object other than a
   directory.  The server responds to this request with a SSH_FXP_STATUS
   message.

6.7 Scanning Directories

   The files in a directory can be listed using the SSH_FXP_OPENDIR and
   SSH_FXP_READDIR requests.  Each SSH_FXP_READDIR request returns one
   or more file names with full file attributes for each file.  The
   client should call SSH_FXP_READDIR repeatedly until it has found the
   file it is looking for or until the server responds with a
   SSH_FXP_STATUS message indicating an error (normally SSH_FX_EOF if
   there are no more files in the directory).  The client should then
   close the handle using the SSH_FXP_CLOSE request.










Ylonen & Lehtinen         Expires April 1, 2002                [Page 15]

Internet-Draft         SSH File Transfer Protocol           October 2001


    The SSH_FXP_OPENDIR opens a directory for reading.  It has the
   following format:

   	uint32     id
   	string     path

   where `id' is the request identifier and `path' is the path name of
   the directory to be listed (without any trailing slash).  See Section
   ``File Names'' for more information on file names.  This will return
   an error if the path does not specify a directory or if the directory
   is not readable.  The server will respond to this request with either
   a SSH_FXP_HANDLE or a SSH_FXP_STATUS message.

    Once the directory has been successfully opened, files (and
   directories) contained in it can be listed using SSH_FXP_READDIR
   requests.  These are of the format

   	uint32     id
   	string     handle

   where `id' is the request identifier, and `handle' is a handle
   returned by SSH_FXP_OPENDIR.  (It is a protocol error to attempt to
   use an ordinary file handle returned by SSH_FXP_OPEN.)

   The server responds to this request with either a SSH_FXP_NAME or a
   SSH_FXP_STATUS message.  One or more names may be returned at a time.
   Full status information is returned for each name in order to speed
   up typical directory listings.

   When the client no longer wishes to read more names from the
   directory, it SHOULD call SSH_FXP_CLOSE for the handle.  The handle
   should be closed regardless of whether an error has occurred or not.

6.8 Retrieving File Attributes

   Very often, file attributes are automatically returned by
   SSH_FXP_READDIR.  However, sometimes there is need to specifically
   retrieve the attributes for a named file.  This can be done using the
   SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.

    SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT
   follows symbolic links on the server, whereas SSH_FXP_LSTAT does not
   follow symbolic links.  Both have the same format:

   	uint32     id
   	string     path

   where `id' is the request identifier, and `path' specifies the file



Ylonen & Lehtinen         Expires April 1, 2002                [Page 16]

Internet-Draft         SSH File Transfer Protocol           October 2001


   system object for which status is to be returned.  The server
   responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS.

    SSH_FXP_FSTAT differs from the others in that it returns status
   information for an open file (identified by the file handle).  Its
   format is as follows:

   	uint32     id
   	string     handle

   where `id' is the request identifier and `handle' is a file handle
   returned by SSH_FXP_OPEN.  The server responds to this request with
   SSH_FXP_ATTRS or SSH_FXP_STATUS.

6.9 Setting File Attributes

   File attributes may be modified using the SSH_FXP_SETSTAT and
   SSH_FXP_FSETSTAT requests.  These requests are used for operations
   such as changing the ownership, permissions or access times, as well
   as for truncating a file.

    The SSH_FXP_SETSTAT request is of the following format:

   	uint32     id
   	string     path
   	ATTRS      attrs

   where `id' is the request identifier, `path' specifies the file
   system object (e.g.  file or directory) whose attributes are to be
   modified, and `attrs' specifies the modifications to be made to its
   attributes.  Attributes are discussed in more detail in Section
   ``File Attributes''.

   An error will be returned if the specified file system object does
   not exist or the user does not have sufficient rights to modify the
   specified attributes.  The server responds to this request with a
   SSH_FXP_STATUS message.

    The SSH_FXP_FSETSTAT request modifies the attributes of a file which
   is already open.  It has the following format:

   	uint32     id
   	string     handle
   	ATTRS      attrs

   where `id' is the request identifier, `handle' (MUST be returned by
   SSH_FXP_OPEN) identifies the file whose attributes are to be
   modified, and `attrs' specifies the modifications to be made to its



Ylonen & Lehtinen         Expires April 1, 2002                [Page 17]

Internet-Draft         SSH File Transfer Protocol           October 2001


   attributes.  Attributes are discussed in more detail in Section
   ``File Attributes''.  The server will respond to this request with
   SSH_FXP_STATUS.

6.10 Dealing with Symbolic links

    The SSH_FXP_READLINK request may be used to read the target of a
   symbolic link.  It would have a data part as follows:

   	uint32     id
   	string     path

   where `id' is the request identifier and `path' specifies the path
   name of the symlink to be read.

   The server will respond with a SSH_FXP_NAME packet containing only
   one name and a dummy attributes value.  The name in the returned
   packet contains the target of the link.  If an error occurs, the
   server may respond with SSH_FXP_STATUS.

    The SSH_FXP_SYMLINK request will create a symbolic link on the
   server.  It is of the following format

   	uint32     id
   	string     linkpath
   	string     targetpath

   where `id' is the request identifier, `linkpath' specifies the path
   name of the symlink to be created and `targetpath' specifies the
   target of the symlink.  The server shall respond with a
   SSH_FXP_STATUS indicating either success (SSH_FX_OK) or an error
   condition.

6.11 Canonicalizing the Server-Side Path Name

    The SSH_FXP_REALPATH request can be used to have the server
   canonicalize any given path name to an absolute path.  This is useful
   for converting path names containing ".." components or relative
   pathnames without a leading slash into absolute paths.  The format of
   the request is as follows:

   	uint32     id
   	string     path

   where `id' is the request identifier and `path' specifies the path
   name to be canonicalized.  The server will respond with a
   SSH_FXP_NAME packet containing only one name and a dummy attributes
   value.  The name is the returned packet will be in canonical form.



Ylonen & Lehtinen         Expires April 1, 2002                [Page 18]

Internet-Draft         SSH File Transfer Protocol           October 2001


   If an error occurs, the server may also respond with SSH_FXP_STATUS.


















































Ylonen & Lehtinen         Expires April 1, 2002                [Page 19]

Internet-Draft         SSH File Transfer Protocol           October 2001


7. Responses from the Server to the Client

   The server responds to the client using one of a few response
   packets.  All requests can return a SSH_FXP_STATUS response upon
   failure.  When the operation is successful, any of the responses may
   be returned (depending on the operation).  If no data needs to be
   returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK
   status is appropriate.  Otherwise, the SSH_FXP_HANDLE message is used
   to return a file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR
   requests), SSH_FXP_DATA is used to return data from SSH_FXP_READ,
   SSH_FXP_NAME is used to return one or more file names from a
   SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is
   used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and
   SSH_FXP_FSTAT requests.

   Exactly one response will be returned for each request.  Each
   response packet contains a request identifier which can be used to
   match each response with the corresponding request.  Note that it is
   legal to have several requests outstanding simultaneously, and the
   server is allowed to send responses to them in a different order from
   the order in which the requests were sent (the result of their
   execution, however, is guaranteed to be as if they had been processed
   one at a time in the order in which the requests were sent).

   Response packets are of the same general format as request packets.
   Each response packet begins with the request identifier.

    The format of the data portion of the SSH_FXP_STATUS response is as
   follows:

   	uint32     id
   	uint32     error/status code
   	string     error message (ISO-10646 UTF-8 [RFC-2279])
   	string     language tag (as defined in [RFC-1766])

   where `id' is the request identifier, and `error/status code'
   indicates the result of the requested operation.  The value SSH_FX_OK
   indicates success, and all other values indicate failure.













Ylonen & Lehtinen         Expires April 1, 2002                [Page 20]

Internet-Draft         SSH File Transfer Protocol           October 2001


    Currently, the following values are defined (other values may be
   defined by future versions of this protocol):

   	#define SSH_FX_OK                            0
   	#define SSH_FX_EOF                           1
   	#define SSH_FX_NO_SUCH_FILE                  2
   	#define SSH_FX_PERMISSION_DENIED             3
   	#define SSH_FX_FAILURE                       4
   	#define SSH_FX_BAD_MESSAGE                   5
   	#define SSH_FX_NO_CONNECTION                 6
   	#define SSH_FX_CONNECTION_LOST               7
   	#define SSH_FX_OP_UNSUPPORTED                8

   SSH_FX_OK
      Indicates successful completion of the operation.

   SSH_FX_EOF
      indicates end-of-file condition; for SSH_FX_READ it means that no
      more data is available in the file, and for SSH_FX_READDIR it
      indicates that no more files are contained in the directory.

   SSH_FX_NO_SUCH_FILE
      is returned when a reference is made to a file which should exist
      but doesn't.

   SSH_FX_PERMISSION_DENIED
      is returned when the authenticated user does not have sufficient
      permissions to perform the operation.

   SSH_FX_FAILURE
      is a generic catch-all error message; it should be returned if an
      error occurs for which there is no more specific error code
      defined.

   SSH_FX_BAD_MESSAGE
      may be returned if a badly formatted packet or protocol
      incompatibility is detected.

   SSH_FX_NO_CONNECTION
      is a pseudo-error which indicates that the client has no
      connection to the server (it can only be generated locally by the
      client, and MUST NOT be returned by servers).

   SSH_FX_CONNECTION_LOST
      is a pseudo-error which indicates that the connection to the
      server has been lost (it can only be generated locally by the
      client, and MUST NOT be returned by servers).




Ylonen & Lehtinen         Expires April 1, 2002                [Page 21]

Internet-Draft         SSH File Transfer Protocol           October 2001


   SSH_FX_OP_UNSUPPORTED
      indicates that an attempt was made to perform an operation which
      is not supported for the server (it may be generated locally by
      the client if e.g.  the version number exchange indicates that a
      required feature is not supported by the server, or it may be
      returned by the server if the server does not implement an
      operation).

   The SSH_FXP_HANDLE response has the following format:

   	uint32     id
   	string     handle

   where `id' is the request identifier, and `handle' is an arbitrary
   string that identifies an open file or directory on the server.  The
   handle is opaque to the client; the client MUST NOT attempt to
   interpret or modify it in any way.  The length of the handle string
   MUST NOT exceed 256 data bytes.

    The SSH_FXP_DATA response has the following format:

   	uint32     id
   	string     data

   where `id' is the request identifier, and `data' is an arbitrary byte
   string containing the requested data.  The data string may be at most
   the number of bytes requested in a SSH_FXP_READ request, but may also
   be shorter if end of file is reached or if the read is from something
   other than a regular file.

    The SSH_FXP_NAME response has the following format:

   	uint32     id
   	uint32     count
   	repeats count times:
   		string     filename
   		string     longname
   		ATTRS      attrs

   where `id' is the request identifier, `count' is the number of names
   returned in this response, and the remaining fields repeat `count'