draft-ietf-secsh-filexfer-04.txt

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

   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



Galbraith, et al.        Expires June 18, 2003                 [Page 22]

Internet-Draft         SSH File Transfer Protocol          December 2002


   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 [UTF-8]
   	uint32     flags

   where `id' is the request identifier, and `path' specifies the file
   system object for which status is to be returned.  The server
   responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS.

   The flags field specify the attribute flags in which the client has
   particular interest.  This is a hint to the server.  For example,
   because retrieving owner / group and acl information can be an
   expensive operation under some operating systems, the server may
   choose not to retrieve this information unless the client expresses a
   specific interest in it.

   The client has no guarantee the server will provide all the fields
   that it has expressed an interest in.

   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
   	uint32     flags

   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:







Galbraith, et al.        Expires June 18, 2003                 [Page 23]

Internet-Draft         SSH File Transfer Protocol          December 2002


   	uint32     id
   	string     path [UTF-8]
   	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
   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 [UTF-8]

   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




Galbraith, et al.        Expires June 18, 2003                 [Page 24]

Internet-Draft         SSH File Transfer Protocol          December 2002


   	uint32     id
   	string     linkpath   [UTF-8]
   	string     targetpath [UTF-8]

   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 [UTF-8]

   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 the name in canonical form and a dummy
   attributes value.  If an error occurs, the server may also respond
   with SSH_FXP_STATUS.

6.11.1 Best practice for dealing with paths

   The client SHOULD treat the results of SSH_FXP_REALPATH as a
   canonical absolute path, even if the path does not appear to be
   absolute.  A client that use REALPATH(".") and treats the result as
   absolute, even if there is no leading slash, will continue to
   function correctly, even when talking to a Windows NT or VMS style
   system, where absolute paths may not begin with a slash.

   For example, if the client wishes to change directory up, and the
   server has returned "c:/x/y/z" from REALPATH, the client SHOULD use
   "c:/x/y/z/..".

   As a second example, if the client wishes to open the file "x.txt" in
   the current directory, and server has returned "dka100:/x/y/z" as the
   canonical path of the directory, the client SHOULD open "dka100:/x/y/
   z/x.txt"







Galbraith, et al.        Expires June 18, 2003                 [Page 25]

Internet-Draft         SSH File Transfer Protocol          December 2002


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.

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










Galbraith, et al.        Expires June 18, 2003                 [Page 26]

Internet-Draft         SSH File Transfer Protocol          December 2002


   	#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
   	#define SSH_FX_INVALID_HANDLE                9
   	#define SSH_FX_NO_SUCH_PATH                  10
   	#define SSH_FX_FILE_ALREADY_EXISTS           11
   	#define SSH_FX_WRITE_PROTECT                 12
   	#define SSH_FX_NO_MEDIA                      13

   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 does not
      exist.

   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



Galbraith, et al.        Expires June 18, 2003                 [Page 27]

Internet-Draft         SSH File Transfer Protocol          December 2002


      client, and MUST NOT be returned by servers).

   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).

   SSH_FX_INVALID_HANDLE
      The handle value was invalid.

   SSH_FX_NO_SUCH_PATH
      The file path does not exist or is invalid.

   SSH_FX_FILE_ALREADY_EXISTS
      The file already exists.

   SSH_FX_WRITE_PROTECT
      The file is on read only media, or the media is write protected.

   SSH_FX_NO_MEDIA
      The requested operation can not be completed because there is no
      media available in the drive.

   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.




Galbraith, et al.        Expires June 18, 2003                 [Page 28]

Internet-Draft         SSH File Transfer Protocol          December 2002


   The SSH_FXP_NAME response has the following format:

   	uint32     id
   	uint32     count
   	repeats count times:
   		string     filename [UTF-8]
   		ATTRS      attrs

   where `id' is the request identifier, `count' is the number of names
   returned in this response, and the remaining fields repeat `count'
   times (so that all three fields are first included for the first
   file, then for the second file, etc).  In the repeated part,
   `filename' is a file name being returned (for SSH_FXP_READDIR, it
   will be a relative name within the directory, without any path
   components; for SSH_FXP_REALPATH it will be an absolute path name),
   and `attrs' is the attributes of the file as described in Section
   ``File Attributes''.

   The SSH_FXP_ATTRS response has the following format:

   	uint32     id
   	ATTRS      attrs

   where `id' is the request identifier, and `attrs' is the returned
   file attributes as described in Section ``File Attributes''.


























Galbraith, et al.        Expires June 18, 2003                 [Page 29]