libssh2/include/libssh2_sftp.h

   1 /* Copyright (c) 2004-2007, Sara Golemon <sarag@libssh2.org>
   2  * All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms,
   5  * with or without modification, are permitted provided
   6  * that the following conditions are met:
   7  *
   8  *   Redistributions of source code must retain the above
   9  *   copyright notice, this list of conditions and the
  10  *   following disclaimer.
  11  *
  12  *   Redistributions in binary form must reproduce the above
  13  *   copyright notice, this list of conditions and the following
  14  *   disclaimer in the documentation and/or other materials
  15  *   provided with the distribution.
  16  *
  17  *   Neither the name of the copyright holder nor the names
  18  *   of any other contributors may be used to endorse or
  19  *   promote products derived from this software without
  20  *   specific prior written permission.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
  23  * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
  24  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  25  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  27  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  28  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  29  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  30  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  31  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  32  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  33  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
  34  * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
  35  * OF SUCH DAMAGE.
  36  */
  37
  38 #ifndef LIBSSH2_SFTP_H
  39 #define LIBSSH2_SFTP_H 1
  40
  41 #ifndef WIN32
  42 #include <unistd.h>
  43 #endif
  44
  45 #ifdef __cplusplus
  46 extern "C" {
  47 #endif
  48
  49 /* Note: Version 6 was documented at the time of writing
  50  * However it was marked as "DO NOT IMPLEMENT" due to pending changes
  51  *
  52  * Let's start with Version 3 (The version found in OpenSSH) and go from there
  53  */
  54 #define LIBSSH2_SFTP_VERSION        3
  55 #define LIBSSH2_SFTP_PACKET_MAXLEN  40000
  56
  57 typedef struct _LIBSSH2_SFTP                LIBSSH2_SFTP;
  58 typedef struct _LIBSSH2_SFTP_HANDLE         LIBSSH2_SFTP_HANDLE;
  59 typedef struct _LIBSSH2_SFTP_ATTRIBUTES     LIBSSH2_SFTP_ATTRIBUTES;
  60
  61 /* Flags for open_ex() */
  62 #define LIBSSH2_SFTP_OPENFILE           0
  63 #define LIBSSH2_SFTP_OPENDIR            1
  64
  65 /* Flags for rename_ex() */
  66 #define LIBSSH2_SFTP_RENAME_OVERWRITE   0x00000001
  67 #define LIBSSH2_SFTP_RENAME_ATOMIC      0x00000002
  68 #define LIBSSH2_SFTP_RENAME_NATIVE      0x00000004
  69
  70 /* Flags for stat_ex() */
  71 #define LIBSSH2_SFTP_STAT               0
  72 #define LIBSSH2_SFTP_LSTAT              1
  73 #define LIBSSH2_SFTP_SETSTAT            2
  74
  75 /* Flags for symlink_ex() */
  76 #define LIBSSH2_SFTP_SYMLINK            0
  77 #define LIBSSH2_SFTP_READLINK           1
  78 #define LIBSSH2_SFTP_REALPATH           2
  79
  80 /* SFTP attribute flag bits */
  81 #define LIBSSH2_SFTP_ATTR_SIZE              0x00000001
  82 #define LIBSSH2_SFTP_ATTR_UIDGID            0x00000002
  83 #define LIBSSH2_SFTP_ATTR_PERMISSIONS       0x00000004
  84 #define LIBSSH2_SFTP_ATTR_ACMODTIME         0x00000008
  85 #define LIBSSH2_SFTP_ATTR_EXTENDED          0x80000000
  86
  87 struct _LIBSSH2_SFTP_ATTRIBUTES {
  88     /* If flags & ATTR_* bit is set, then the value in this struct will be meaningful
  89      * Otherwise it should be ignored
  90      */
  91     unsigned long flags;
  92
  93     libssh2_uint64_t filesize;
  94     unsigned long uid, gid;
  95     unsigned long permissions;
  96     unsigned long atime, mtime;
  97 };
  98
  99 /* SFTP filetypes */
 100 #define LIBSSH2_SFTP_TYPE_REGULAR           1
 101 #define LIBSSH2_SFTP_TYPE_DIRECTORY         2
 102 #define LIBSSH2_SFTP_TYPE_SYMLINK           3
 103 #define LIBSSH2_SFTP_TYPE_SPECIAL           4
 104 #define LIBSSH2_SFTP_TYPE_UNKNOWN           5
 105 #define LIBSSH2_SFTP_TYPE_SOCKET            6
 106 #define LIBSSH2_SFTP_TYPE_CHAR_DEVICE       7
 107 #define LIBSSH2_SFTP_TYPE_BLOCK_DEVICE      8
 108 #define LIBSSH2_SFTP_TYPE_FIFO              9
 109
 110 /*
 111  * Reproduce the POSIX file modes here for systems that are not
 112  * POSIX compliant.
 113  *
 114  * These is used in "permissions" of "struct _LIBSSH2_SFTP_ATTRIBUTES"
 115  */
 116 /* File type */
 117 #define LIBSSH2_SFTP_S_IFMT         0170000     /* type of file mask */
 118 #define LIBSSH2_SFTP_S_IFIFO        0010000     /* named pipe (fifo) */
 119 #define LIBSSH2_SFTP_S_IFCHR        0020000     /* character special */
 120 #define LIBSSH2_SFTP_S_IFDIR        0040000     /* directory */
 121 #define LIBSSH2_SFTP_S_IFBLK        0060000     /* block special */
 122 #define LIBSSH2_SFTP_S_IFREG        0100000     /* regular */
 123 #define LIBSSH2_SFTP_S_IFLNK        0120000     /* symbolic link */
 124 #define LIBSSH2_SFTP_S_IFSOCK       0140000     /* socket */
 125
 126 /* File mode */
 127 /* Read, write, execute/search by owner */
 128 #define LIBSSH2_SFTP_S_IRWXU        0000700     /* RWX mask for owner */
 129 #define LIBSSH2_SFTP_S_IRUSR        0000400     /* R for owner */
 130 #define LIBSSH2_SFTP_S_IWUSR        0000200     /* W for owner */
 131 #define LIBSSH2_SFTP_S_IXUSR        0000100     /* X for owner */
 132 /* Read, write, execute/search by group */
 133 #define LIBSSH2_SFTP_S_IRWXG        0000070     /* RWX mask for group */
 134 #define LIBSSH2_SFTP_S_IRGRP        0000040     /* R for group */
 135 #define LIBSSH2_SFTP_S_IWGRP        0000020     /* W for group */
 136 #define LIBSSH2_SFTP_S_IXGRP        0000010     /* X for group */
 137 /* Read, write, execute/search by others */
 138 #define LIBSSH2_SFTP_S_IRWXO        0000007     /* RWX mask for other */
 139 #define LIBSSH2_SFTP_S_IROTH        0000004     /* R for other */
 140 #define LIBSSH2_SFTP_S_IWOTH        0000002     /* W for other */
 141 #define LIBSSH2_SFTP_S_IXOTH        0000001     /* X for other */
 142
 143 /* SFTP File Transfer Flags -- (e.g. flags parameter to sftp_open())
 144  * Danger will robinson... APPEND doesn't have any effect on OpenSSH servers */
 145 #define LIBSSH2_FXF_READ                        0x00000001
 146 #define LIBSSH2_FXF_WRITE                       0x00000002
 147 #define LIBSSH2_FXF_APPEND                      0x00000004
 148 #define LIBSSH2_FXF_CREAT                       0x00000008
 149 #define LIBSSH2_FXF_TRUNC                       0x00000010
 150 #define LIBSSH2_FXF_EXCL                        0x00000020
 151
 152 /* SFTP Status Codes (returned by libssh2_sftp_last_error() ) */
 153 #define LIBSSH2_FX_OK                       0
 154 #define LIBSSH2_FX_EOF                      1
 155 #define LIBSSH2_FX_NO_SUCH_FILE             2
 156 #define LIBSSH2_FX_PERMISSION_DENIED        3
 157 #define LIBSSH2_FX_FAILURE                  4
 158 #define LIBSSH2_FX_BAD_MESSAGE              5
 159 #define LIBSSH2_FX_NO_CONNECTION            6
 160 #define LIBSSH2_FX_CONNECTION_LOST          7
 161 #define LIBSSH2_FX_OP_UNSUPPORTED           8
 162 #define LIBSSH2_FX_INVALID_HANDLE           9
 163 #define LIBSSH2_FX_NO_SUCH_PATH             10
 164 #define LIBSSH2_FX_FILE_ALREADY_EXISTS      11
 165 #define LIBSSH2_FX_WRITE_PROTECT            12
 166 #define LIBSSH2_FX_NO_MEDIA                 13
 167 #define LIBSSH2_FX_NO_SPACE_ON_FILESYSTEM   14
 168 #define LIBSSH2_FX_QUOTA_EXCEEDED           15
 169 #define LIBSSH2_FX_UNKNOWN_PRINCIPLE        16 /* Initial mis-spelling */
 170 #define LIBSSH2_FX_UNKNOWN_PRINCIPAL        16
 171 #define LIBSSH2_FX_LOCK_CONFlICT            17 /* Initial mis-spelling */
 172 #define LIBSSH2_FX_LOCK_CONFLICT            17
 173 #define LIBSSH2_FX_DIR_NOT_EMPTY            18
 174 #define LIBSSH2_FX_NOT_A_DIRECTORY          19
 175 #define LIBSSH2_FX_INVALID_FILENAME         20
 176 #define LIBSSH2_FX_LINK_LOOP                21
 177
 178 /* Returned by any function that would block during a read/write opperation */
 179 #define LIBSSH2SFTP_EAGAIN LIBSSH2_ERROR_EAGAIN
 180
 181 /* SFTP API */
 182 LIBSSH2_API LIBSSH2_SFTP *libssh2_sftp_init(LIBSSH2_SESSION *session);
 183 LIBSSH2_API int libssh2_sftp_shutdown(LIBSSH2_SFTP *sftp);
 184 LIBSSH2_API unsigned long libssh2_sftp_last_error(LIBSSH2_SFTP *sftp);
 185
 186 /* File / Directory Ops */
 187 LIBSSH2_API LIBSSH2_SFTP_HANDLE *libssh2_sftp_open_ex(LIBSSH2_SFTP *sftp, const char *filename, unsigned int filename_len,
 188                                                       unsigned long flags, long mode, int open_type);
 189 #define libssh2_sftp_open(sftp, filename, flags, mode) \
 190                     libssh2_sftp_open_ex((sftp), (filename), strlen(filename), (flags), (mode), LIBSSH2_SFTP_OPENFILE)
 191 #define libssh2_sftp_opendir(sftp, path) \
 192                     libssh2_sftp_open_ex((sftp), (path), strlen(path), 0, 0, LIBSSH2_SFTP_OPENDIR)
 193
 194 LIBSSH2_API ssize_t libssh2_sftp_read(LIBSSH2_SFTP_HANDLE *handle, char *buffer, size_t buffer_maxlen);
 195
 196 LIBSSH2_API int libssh2_sftp_readdir_ex(LIBSSH2_SFTP_HANDLE *handle, char *buffer, size_t buffer_maxlen,
 197                                         char *longentry, size_t longentry_maxlen,
 198                                         LIBSSH2_SFTP_ATTRIBUTES *attrs);
 199 #define libssh2_sftp_readdir(handle, buffer, buffer_maxlen, attrs) \
 200                     libssh2_sftp_readdir_ex((handle), (buffer), (buffer_maxlen), NULL, 0, (attrs))
 201
 202 LIBSSH2_API ssize_t libssh2_sftp_write(LIBSSH2_SFTP_HANDLE *handle, const char *buffer, size_t count);
 203
 204 LIBSSH2_API int libssh2_sftp_close_handle(LIBSSH2_SFTP_HANDLE *handle);
 205 #define libssh2_sftp_close(handle)                  libssh2_sftp_close_handle(handle)
 206 #define libssh2_sftp_closedir(handle)               libssh2_sftp_close_handle(handle)
 207
 208 LIBSSH2_API void libssh2_sftp_seek(LIBSSH2_SFTP_HANDLE *handle, size_t offset);
 209 #define libssh2_sftp_rewind(handle)         libssh2_sftp_seek((handle), 0)
 210
 211 LIBSSH2_API size_t libssh2_sftp_tell(LIBSSH2_SFTP_HANDLE *handle);
 212
 213 LIBSSH2_API int libssh2_sftp_fstat_ex(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_ATTRIBUTES *attrs, int setstat);
 214 #define libssh2_sftp_fstat(handle, attrs)               libssh2_sftp_fstat_ex((handle), (attrs), 0)
 215 #define libssh2_sftp_fsetstat(handle, attrs)            libssh2_sftp_fstat_ex((handle), (attrs), 1)
 216
 217
 218
 219 /* Miscellaneous Ops */
 220 LIBSSH2_API int libssh2_sftp_rename_ex(LIBSSH2_SFTP *sftp,  const char *source_filename,    unsigned int srouce_filename_len,
 221                                                             const char *dest_filename,      unsigned int dest_filename_len,
 222                                                             long flags);
 223 #define libssh2_sftp_rename(sftp, sourcefile, destfile)     libssh2_sftp_rename_ex((sftp), (sourcefile), strlen(sourcefile), (destfile), strlen(destfile), \
 224                                                             LIBSSH2_SFTP_RENAME_OVERWRITE | LIBSSH2_SFTP_RENAME_ATOMIC | LIBSSH2_SFTP_RENAME_NATIVE)
 225
 226 LIBSSH2_API int libssh2_sftp_unlink_ex(LIBSSH2_SFTP *sftp, const char *filename, unsigned int filename_len);
 227 #define libssh2_sftp_unlink(sftp, filename)                 libssh2_sftp_unlink_ex((sftp), (filename), strlen(filename))
 228
 229 LIBSSH2_API int libssh2_sftp_mkdir_ex(LIBSSH2_SFTP *sftp, const char *path, unsigned int path_len, long mode);
 230 #define libssh2_sftp_mkdir(sftp, path, mode)                libssh2_sftp_mkdir_ex((sftp), (path), strlen(path), (mode))
 231
 232 LIBSSH2_API int libssh2_sftp_rmdir_ex(LIBSSH2_SFTP *sftp, const char *path, unsigned int path_len);
 233 #define libssh2_sftp_rmdir(sftp, path)                      libssh2_sftp_rmdir_ex((sftp), (path), strlen(path))
 234
 235 LIBSSH2_API int libssh2_sftp_stat_ex(LIBSSH2_SFTP *sftp, const char *path, unsigned int path_len, int stat_type, LIBSSH2_SFTP_ATTRIBUTES *attrs);
 236 #define libssh2_sftp_stat(sftp, path, attrs)                libssh2_sftp_stat_ex((sftp), (path), strlen(path), LIBSSH2_SFTP_STAT, (attrs))
 237 #define libssh2_sftp_lstat(sftp, path, attrs)               libssh2_sftp_stat_ex((sftp), (path), strlen(path), LIBSSH2_SFTP_LSTAT, (attrs))
 238 #define libssh2_sftp_setstat(sftp, path, attrs)             libssh2_sftp_stat_ex((sftp), (path), strlen(path), LIBSSH2_SFTP_SETSTAT, (attrs))
 239
 240 LIBSSH2_API int libssh2_sftp_symlink_ex(LIBSSH2_SFTP *sftp, const char *path, unsigned int path_len, char *target, unsigned int target_len, int link_type);
 241 #define libssh2_sftp_symlink(sftp, orig, linkpath)          libssh2_sftp_symlink_ex((sftp), (orig), strlen(orig), (linkpath), strlen(linkpath), LIBSSH2_SFTP_SYMLINK)
 242 #define libssh2_sftp_readlink(sftp, path, target, maxlen)   libssh2_sftp_symlink_ex((sftp), (path), strlen(path), (target), (maxlen), LIBSSH2_SFTP_READLINK)
 243 #define libssh2_sftp_realpath(sftp, path, target, maxlen)   libssh2_sftp_symlink_ex((sftp), (path), strlen(path), (target), (maxlen), LIBSSH2_SFTP_REALPATH)
 244
 245 #ifdef __cplusplus
 246 } /* extern "C" */
 247 #endif
 248
 249 #endif /* LIBSSH2_SFTP_H */