draft-ietf-secsh-filexfer-03.txt

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

   	uint32        id
   	string        filename [UTF-8]
   	uint32        pflags
   	ATTRS         attrs

   The `id' field is the request identifier as for all requests.

   The `filename' field specifies the file name.  See Section ``File
   Names'' for more information.

   The `pflags' field is a bitmask.  The following bits have been
   defined.

   	#define SSH_FXF_READ            0x00000001
   	#define SSH_FXF_WRITE           0x00000002
   	#define SSH_FXF_APPEND          0x00000004
   	#define SSH_FXF_CREAT           0x00000008
   	#define SSH_FXF_TRUNC           0x00000010
   	#define SSH_FXF_EXCL            0x00000020
   	#define SSH_FXF_TEXT            0x00000040

   These have the following meanings:

   SSH_FXF_READ
      Open the file for reading.

   SSH_FXF_WRITE
      Open the file for writing.  If both this and SSH_FXF_READ are
      specified, the file is opened for both reading and writing.

   SSH_FXF_APPEND
      Force all writes to append data at the end of the file.  The
      offset parameter to write will be ignored.

   SSH_FXF_CREAT
      If this flag is specified, then a new file will be created if one
      does not already exist (if O_TRUNC is specified, the new file will
      be truncated to zero length if it previously exists).

   SSH_FXF_TRUNC
      Forces an existing file with the same name to be truncated to zero
      length when creating a file by specifying SSH_FXF_CREAT.
      SSH_FXF_CREAT MUST also be specified if this flag is used.

   SSH_FXF_EXCL
      Causes the request to fail if the named file already exists.
      SSH_FXF_CREAT MUST also be specified if this flag is used.




Galbraith, et al.        Expires April 16, 2003                [Page 15]

Internet-Draft         SSH File Transfer Protocol           October 2002


   SSH_FXF_TEXT
      Indicates that the server should treat the file as text and
      convert it to the canonical newline convention in use.  (See
      Determining Server Newline Convention. (Section 4.3)

      When a file is opened with the FXF_TEXT flag, the offset field in
      both the read and write function are ignored.

      Servers MUST correctly process multiple parallel reads and writes
      correctly in this mode.  Naturally, it is permissible for them to
      do this by serializing the requests.  It would not be possible for
      a client to reliably detect a server that does not implement
      parallel writes in time to prevent damage.

      Clients SHOULD use the SSH_FXF_APPEND flag to append data to a
      text file rather then using write with a calculated offset.

      To support seeks on text file the following SSH_FXP_EXTENDED
      packet is defined.



   	string "text-seek"
   	string file-handle
   	uint64 line-number

      line-number is the index of the line number to seek to, where byte
      0 in the file is line number 0, and the byte directly following
      the first newline sequence in the file is line number 1 and so on.

      The response to a "text-seek" request is an SSH_FXP_STATUS
      message.

      An attempt to seek past the end-of-file should result in a
      SSH_FX_EOF status.

      Servers SHOULD support at least one "text-seek" in order to
      support resume.  However, a client MUST be prepared to receive
      SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation.
      The client can then try a fall-back strategy, if it has one.

      Clients MUST be prepared to handle SSH_FX_OP_UNSUPPORTED returned
      for read or write operations that are not sequential.

   The `attrs' field specifies the initial attributes for the file.
   Default values will be used for those attributes that are not
   specified.  See Section ``File Attributes'' for more information.




Galbraith, et al.        Expires April 16, 2003                [Page 16]

Internet-Draft         SSH File Transfer Protocol           October 2002


   The response to this message will be either SSH_FXP_HANDLE (if the
   operation is successful) or SSH_FXP_STATUS (if the operation fails).

   A file is closed by using the SSH_FXP_CLOSE request.  Its data field
   has the following format:

   	uint32     id
   	string     handle

   where `id' is the request identifier, and `handle' is a handle
   previously returned in the response to SSH_FXP_OPEN or
   SSH_FXP_OPENDIR.  The handle becomes invalid immediately after this
   request has been sent.

   The response to this request will be a SSH_FXP_STATUS message.  One
   should note that on some server platforms even a close can fail.
   This can happen e.g.  if the server operating system caches writes,
   and an error occurs while flushing cached writes during the close.

6.4 Reading and Writing

   Once a file has been opened, it can be read using the SSH_FXP_READ
   message, which has the following format:

   	uint32     id
   	string     handle
   	uint64     offset
   	uint32     len

   where `id' is the request identifier, `handle' is an open file handle
   returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative
   to the beginning of the file from where to start reading, and `len'
   is the maximum number of bytes to read.

   In response to this request, the server will read as many bytes as it
   can from the file (up to `len'), and return them in a SSH_FXP_DATA
   message.  If an error occurs or EOF is encountered before reading any
   data, the server will respond with SSH_FXP_STATUS.  For normal disk
   files, it is guaranteed that this will read the specified number of
   bytes, or up to end of file.  For e.g.  device files this may return
   fewer bytes than requested.

   Writing to a file is achieved using the SSH_FXP_WRITE message, which
   has the following format:







Galbraith, et al.        Expires April 16, 2003                [Page 17]

Internet-Draft         SSH File Transfer Protocol           October 2002


   	uint32     id
   	string     handle
   	uint64     offset
   	string     data

   where `id' is a request identifier, `handle' is a file handle
   returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the
   beginning of the file where to start writing, and `data' is the data
   to be written.

   The write will extend the file if writing beyond the end of the file.
   It is legal to write way beyond the end of the file; the semantics
   are to write zeroes from the end of the file to the specified offset
   and then the data.  On most operating systems, such writes do not
   allocate disk space but instead leave "holes" in the file.

   The server responds to a write request with a SSH_FXP_STATUS message.

6.5 Removing and Renaming Files

   Files can be removed using the SSH_FXP_REMOVE message.  It has the
   following format:

   	uint32     id
   	string     filename [UTF-8]

   where `id' is the request identifier and `filename' is the name of
   the file to be removed.  See Section ``File Names'' for more
   information.  This request cannot be used to remove directories.

   The server will respond to this request with a SSH_FXP_STATUS
   message.

   Files (and directories) can be renamed using the SSH_FXP_RENAME
   message.  Its data is as follows:

   	uint32     id
   	string     oldpath [UTF-8]
   	string     newpath [UTF-8]

   where `id' is the request identifier, `oldpath' is the name of an
   existing file or directory, and `newpath' is the new name for the
   file or directory.  It is an error if there already exists a file
   with the name specified by newpath.  The server may also fail rename
   requests in other situations, for example if `oldpath' and `newpath'
   point to different file systems on the server.

   The server will respond to this request with a SSH_FXP_STATUS



Galbraith, et al.        Expires April 16, 2003                [Page 18]

Internet-Draft         SSH File Transfer Protocol           October 2002


   message.

6.6 Creating and Deleting Directories

   New directories can be created using the SSH_FXP_MKDIR request.  It
   has the following format:

   	uint32     id
   	string     path [UTF-8]
   	ATTRS      attrs

   where `id' is the request identifier.

   `path' specifies the directory to be created.  See Section ``File
   Names'' for more information on file names.

   `attrs' specifies the attributes that should be applied to it upon
   creation.  Attributes are discussed in more detail in Section ``File
   Attributes''.

   The server will respond to this request with a SSH_FXP_STATUS
   message.  If a file or directory with the specified path already
   exists, an error will be returned.

   Directories can be removed using the SSH_FXP_RMDIR request, which has
   the following format:

   	uint32     id
   	string     path [UTF-8]

   where `id' is the request identifier, and `path' specifies the
   directory to be removed.  See Section ``File Names'' for more
   information on file names.

   The server responds to this request with a SSH_FXP_STATUS message.
   Errors may be returned from this operation for various reasons,
   including, but not limited to, the path does not exist, the path does
   not refer to a directory object, the directory is not empty, or the
   user has insufficient access or permission to perform the requested
   operation.

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



Galbraith, et al.        Expires April 16, 2003                [Page 19]

Internet-Draft         SSH File Transfer Protocol           October 2002


   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.

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

   	uint32     id
   	string     path [UTF-8]

   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.

   If there are no more names available to be read, the server MUST
   respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF.

   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



Galbraith, et al.        Expires April 16, 2003                [Page 20]

Internet-Draft         SSH File Transfer Protocol           October 2002


   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:

   	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



Galbraith, et al.        Expires April 16, 2003                [Page 21]

Internet-Draft         SSH File Transfer Protocol           October 2002