libssh2/share/man/man3/libssh2_sftp_rename_ex.3

   1 .\" $Id: libssh2_sftp_rename_ex.3,v 1.1 2007/06/14 16:08:43 jehousley Exp $
   2 .\"
   3 .TH libssh2_sftp_rename_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual"
   4 .SH NAME
   5 libssh2_sftp_rename_ex - rename a file
   6 .SH SYNOPSIS
   7 #include <libssh2.h>
   8 #include <libssh2_sftp.h>
   9
  10 int
  11 libssh2_sftp_rename_ex(LIBSSH2_SFTP *sftp, const char *source_filename, unsigned int source_filename_len, const char *dest_filename, unsigned int dest_filename_len, long flags);
  12
  13 int
  14 libssh2_sftp_rename_ex(LIBSSH2_SFTP *sftp, const char *source_filename, const char *dest_filename);
  15
  16 .SH DESCRIPTION
  17 \fIsftp\fP - SFTP instance as returned by
  18 .BR libssh2_sftp_init(3)
  19
  20 \fIsourcefile\fP - Path and name of the existing filesystem entry
  21
  22 \fIsourcefile_len\fP - Length of the path and name of the existing
  23 filesystem entry
  24
  25 \fIdestfile\fP - Path and name of the target filesystem entry
  26
  27 \fIdestfile_len\fP - Length of the path and name of the target
  28 filesystem entry
  29
  30 \fIflags\fP -
  31 Bitmask flags made up of LIBSSH2_SFTP_RENAME_* constants.
  32
  33 Rename a filesystem object on the remote filesystem. The semantics of
  34 this command typically include the ability to move a filsystem object
  35 between folders and/or filesystem mounts. If the LIBSSH2_SFTP_RENAME_OVERWRITE
  36 flag is not set and the destfile entry already exists, the operation
  37 will fail. Use of the other two flags indicate a preference (but not a
  38 requirement) for the remote end to perform an atomic rename operation
  39 and/or using native system calls when possible.
  40
  41 .SH RETURN VALUE
  42 Return 0 on success or negative on failure.  It returns
  43 LIBSSH2_ERROR_EAGAIN when it would otherwise block. While
  44 LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se.
  45
  46 .SH ERRORS
  47 \fILIBSSH2_ERROR_ALLOC\fP -  An internal memory allocation call failed.
  48
  49 \fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket.
  50
  51 \fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP -
  52
  53 \fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was
  54 received on the socket, or an SFTP operation caused an errorcode to
  55 be returned by the server.
  56
  57 .SH SEE ALSO
  58 .BR libssh2_sftp_init(3)