libssh2_sftp.h (16768B)
1/* Copyright (c) 2004-2008, 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#include "libssh2.h" 42 43#ifndef LIBSSH2_WIN32 44#include <unistd.h> 45#endif 46 47#ifdef __cplusplus 48extern "C" { 49#endif 50 51/* Note: Version 6 was documented at the time of writing 52 * However it was marked as "DO NOT IMPLEMENT" due to pending changes 53 * 54 * Let's start with Version 3 (The version found in OpenSSH) and go from there 55 */ 56#define LIBSSH2_SFTP_VERSION 3 57 58typedef struct _LIBSSH2_SFTP LIBSSH2_SFTP; 59typedef struct _LIBSSH2_SFTP_HANDLE LIBSSH2_SFTP_HANDLE; 60typedef struct _LIBSSH2_SFTP_ATTRIBUTES LIBSSH2_SFTP_ATTRIBUTES; 61typedef struct _LIBSSH2_SFTP_STATVFS LIBSSH2_SFTP_STATVFS; 62 63/* Flags for open_ex() */ 64#define LIBSSH2_SFTP_OPENFILE 0 65#define LIBSSH2_SFTP_OPENDIR 1 66 67/* Flags for rename_ex() */ 68#define LIBSSH2_SFTP_RENAME_OVERWRITE 0x00000001 69#define LIBSSH2_SFTP_RENAME_ATOMIC 0x00000002 70#define LIBSSH2_SFTP_RENAME_NATIVE 0x00000004 71 72/* Flags for stat_ex() */ 73#define LIBSSH2_SFTP_STAT 0 74#define LIBSSH2_SFTP_LSTAT 1 75#define LIBSSH2_SFTP_SETSTAT 2 76 77/* Flags for symlink_ex() */ 78#define LIBSSH2_SFTP_SYMLINK 0 79#define LIBSSH2_SFTP_READLINK 1 80#define LIBSSH2_SFTP_REALPATH 2 81 82/* Flags for sftp_mkdir() */ 83#define LIBSSH2_SFTP_DEFAULT_MODE -1 84 85/* SFTP attribute flag bits */ 86#define LIBSSH2_SFTP_ATTR_SIZE 0x00000001 87#define LIBSSH2_SFTP_ATTR_UIDGID 0x00000002 88#define LIBSSH2_SFTP_ATTR_PERMISSIONS 0x00000004 89#define LIBSSH2_SFTP_ATTR_ACMODTIME 0x00000008 90#define LIBSSH2_SFTP_ATTR_EXTENDED 0x80000000 91 92/* SFTP statvfs flag bits */ 93#define LIBSSH2_SFTP_ST_RDONLY 0x00000001 94#define LIBSSH2_SFTP_ST_NOSUID 0x00000002 95 96struct _LIBSSH2_SFTP_ATTRIBUTES { 97 /* If flags & ATTR_* bit is set, then the value in this struct will be 98 * meaningful Otherwise it should be ignored 99 */ 100 unsigned long flags; 101 102 libssh2_uint64_t filesize; 103 unsigned long uid, gid; 104 unsigned long permissions; 105 unsigned long atime, mtime; 106}; 107 108struct _LIBSSH2_SFTP_STATVFS { 109 libssh2_uint64_t f_bsize; /* file system block size */ 110 libssh2_uint64_t f_frsize; /* fragment size */ 111 libssh2_uint64_t f_blocks; /* size of fs in f_frsize units */ 112 libssh2_uint64_t f_bfree; /* # free blocks */ 113 libssh2_uint64_t f_bavail; /* # free blocks for non-root */ 114 libssh2_uint64_t f_files; /* # inodes */ 115 libssh2_uint64_t f_ffree; /* # free inodes */ 116 libssh2_uint64_t f_favail; /* # free inodes for non-root */ 117 libssh2_uint64_t f_fsid; /* file system ID */ 118 libssh2_uint64_t f_flag; /* mount flags */ 119 libssh2_uint64_t f_namemax; /* maximum filename length */ 120}; 121 122/* SFTP filetypes */ 123#define LIBSSH2_SFTP_TYPE_REGULAR 1 124#define LIBSSH2_SFTP_TYPE_DIRECTORY 2 125#define LIBSSH2_SFTP_TYPE_SYMLINK 3 126#define LIBSSH2_SFTP_TYPE_SPECIAL 4 127#define LIBSSH2_SFTP_TYPE_UNKNOWN 5 128#define LIBSSH2_SFTP_TYPE_SOCKET 6 129#define LIBSSH2_SFTP_TYPE_CHAR_DEVICE 7 130#define LIBSSH2_SFTP_TYPE_BLOCK_DEVICE 8 131#define LIBSSH2_SFTP_TYPE_FIFO 9 132 133/* 134 * Reproduce the POSIX file modes here for systems that are not POSIX 135 * compliant. 136 * 137 * These is used in "permissions" of "struct _LIBSSH2_SFTP_ATTRIBUTES" 138 */ 139/* File type */ 140#define LIBSSH2_SFTP_S_IFMT 0170000 /* type of file mask */ 141#define LIBSSH2_SFTP_S_IFIFO 0010000 /* named pipe (fifo) */ 142#define LIBSSH2_SFTP_S_IFCHR 0020000 /* character special */ 143#define LIBSSH2_SFTP_S_IFDIR 0040000 /* directory */ 144#define LIBSSH2_SFTP_S_IFBLK 0060000 /* block special */ 145#define LIBSSH2_SFTP_S_IFREG 0100000 /* regular */ 146#define LIBSSH2_SFTP_S_IFLNK 0120000 /* symbolic link */ 147#define LIBSSH2_SFTP_S_IFSOCK 0140000 /* socket */ 148 149/* File mode */ 150/* Read, write, execute/search by owner */ 151#define LIBSSH2_SFTP_S_IRWXU 0000700 /* RWX mask for owner */ 152#define LIBSSH2_SFTP_S_IRUSR 0000400 /* R for owner */ 153#define LIBSSH2_SFTP_S_IWUSR 0000200 /* W for owner */ 154#define LIBSSH2_SFTP_S_IXUSR 0000100 /* X for owner */ 155/* Read, write, execute/search by group */ 156#define LIBSSH2_SFTP_S_IRWXG 0000070 /* RWX mask for group */ 157#define LIBSSH2_SFTP_S_IRGRP 0000040 /* R for group */ 158#define LIBSSH2_SFTP_S_IWGRP 0000020 /* W for group */ 159#define LIBSSH2_SFTP_S_IXGRP 0000010 /* X for group */ 160/* Read, write, execute/search by others */ 161#define LIBSSH2_SFTP_S_IRWXO 0000007 /* RWX mask for other */ 162#define LIBSSH2_SFTP_S_IROTH 0000004 /* R for other */ 163#define LIBSSH2_SFTP_S_IWOTH 0000002 /* W for other */ 164#define LIBSSH2_SFTP_S_IXOTH 0000001 /* X for other */ 165 166/* macros to check for specific file types, added in 1.2.5 */ 167#define LIBSSH2_SFTP_S_ISLNK(m) \ 168 (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFLNK) 169#define LIBSSH2_SFTP_S_ISREG(m) \ 170 (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFREG) 171#define LIBSSH2_SFTP_S_ISDIR(m) \ 172 (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFDIR) 173#define LIBSSH2_SFTP_S_ISCHR(m) \ 174 (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFCHR) 175#define LIBSSH2_SFTP_S_ISBLK(m) \ 176 (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFBLK) 177#define LIBSSH2_SFTP_S_ISFIFO(m) \ 178 (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFIFO) 179#define LIBSSH2_SFTP_S_ISSOCK(m) \ 180 (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFSOCK) 181 182/* SFTP File Transfer Flags -- (e.g. flags parameter to sftp_open()) 183 * Danger will robinson... APPEND doesn't have any effect on OpenSSH servers */ 184#define LIBSSH2_FXF_READ 0x00000001 185#define LIBSSH2_FXF_WRITE 0x00000002 186#define LIBSSH2_FXF_APPEND 0x00000004 187#define LIBSSH2_FXF_CREAT 0x00000008 188#define LIBSSH2_FXF_TRUNC 0x00000010 189#define LIBSSH2_FXF_EXCL 0x00000020 190 191/* SFTP Status Codes (returned by libssh2_sftp_last_error() ) */ 192#define LIBSSH2_FX_OK 0UL 193#define LIBSSH2_FX_EOF 1UL 194#define LIBSSH2_FX_NO_SUCH_FILE 2UL 195#define LIBSSH2_FX_PERMISSION_DENIED 3UL 196#define LIBSSH2_FX_FAILURE 4UL 197#define LIBSSH2_FX_BAD_MESSAGE 5UL 198#define LIBSSH2_FX_NO_CONNECTION 6UL 199#define LIBSSH2_FX_CONNECTION_LOST 7UL 200#define LIBSSH2_FX_OP_UNSUPPORTED 8UL 201#define LIBSSH2_FX_INVALID_HANDLE 9UL 202#define LIBSSH2_FX_NO_SUCH_PATH 10UL 203#define LIBSSH2_FX_FILE_ALREADY_EXISTS 11UL 204#define LIBSSH2_FX_WRITE_PROTECT 12UL 205#define LIBSSH2_FX_NO_MEDIA 13UL 206#define LIBSSH2_FX_NO_SPACE_ON_FILESYSTEM 14UL 207#define LIBSSH2_FX_QUOTA_EXCEEDED 15UL 208#define LIBSSH2_FX_UNKNOWN_PRINCIPLE 16UL /* Initial mis-spelling */ 209#define LIBSSH2_FX_UNKNOWN_PRINCIPAL 16UL 210#define LIBSSH2_FX_LOCK_CONFlICT 17UL /* Initial mis-spelling */ 211#define LIBSSH2_FX_LOCK_CONFLICT 17UL 212#define LIBSSH2_FX_DIR_NOT_EMPTY 18UL 213#define LIBSSH2_FX_NOT_A_DIRECTORY 19UL 214#define LIBSSH2_FX_INVALID_FILENAME 20UL 215#define LIBSSH2_FX_LINK_LOOP 21UL 216 217/* Returned by any function that would block during a read/write operation */ 218#define LIBSSH2SFTP_EAGAIN LIBSSH2_ERROR_EAGAIN 219 220/* SFTP API */ 221LIBSSH2_API LIBSSH2_SFTP *libssh2_sftp_init(LIBSSH2_SESSION *session); 222LIBSSH2_API int libssh2_sftp_shutdown(LIBSSH2_SFTP *sftp); 223LIBSSH2_API unsigned long libssh2_sftp_last_error(LIBSSH2_SFTP *sftp); 224LIBSSH2_API LIBSSH2_CHANNEL *libssh2_sftp_get_channel(LIBSSH2_SFTP *sftp); 225 226/* File / Directory Ops */ 227LIBSSH2_API LIBSSH2_SFTP_HANDLE * 228libssh2_sftp_open_ex(LIBSSH2_SFTP *sftp, 229 const char *filename, 230 unsigned int filename_len, 231 unsigned long flags, 232 long mode, int open_type); 233#define libssh2_sftp_open(sftp, filename, flags, mode) \ 234 libssh2_sftp_open_ex((sftp), \ 235 (filename), (unsigned int)strlen(filename), \ 236 (flags), (mode), LIBSSH2_SFTP_OPENFILE) 237#define libssh2_sftp_opendir(sftp, path) \ 238 libssh2_sftp_open_ex((sftp), \ 239 (path), (unsigned int)strlen(path), \ 240 0, 0, LIBSSH2_SFTP_OPENDIR) 241LIBSSH2_API LIBSSH2_SFTP_HANDLE * 242libssh2_sftp_open_ex_r(LIBSSH2_SFTP *sftp, 243 const char *filename, 244 size_t filename_len, 245 unsigned long flags, 246 long mode, int open_type, 247 LIBSSH2_SFTP_ATTRIBUTES *attrs); 248#define libssh2_sftp_open_r(sftp, filename, flags, mode, attrs) \ 249 libssh2_sftp_open_ex_r((sftp), (filename), strlen(filename), \ 250 (flags), (mode), LIBSSH2_SFTP_OPENFILE, \ 251 (attrs)) 252 253LIBSSH2_API ssize_t libssh2_sftp_read(LIBSSH2_SFTP_HANDLE *handle, 254 char *buffer, size_t buffer_maxlen); 255 256LIBSSH2_API int libssh2_sftp_readdir_ex(LIBSSH2_SFTP_HANDLE *handle, \ 257 char *buffer, size_t buffer_maxlen, 258 char *longentry, 259 size_t longentry_maxlen, 260 LIBSSH2_SFTP_ATTRIBUTES *attrs); 261#define libssh2_sftp_readdir(handle, buffer, buffer_maxlen, attrs) \ 262 libssh2_sftp_readdir_ex((handle), (buffer), (buffer_maxlen), NULL, 0, \ 263 (attrs)) 264 265LIBSSH2_API ssize_t libssh2_sftp_write(LIBSSH2_SFTP_HANDLE *handle, 266 const char *buffer, size_t count); 267LIBSSH2_API int libssh2_sftp_fsync(LIBSSH2_SFTP_HANDLE *handle); 268 269LIBSSH2_API int libssh2_sftp_close_handle(LIBSSH2_SFTP_HANDLE *handle); 270#define libssh2_sftp_close(handle) libssh2_sftp_close_handle(handle) 271#define libssh2_sftp_closedir(handle) libssh2_sftp_close_handle(handle) 272 273LIBSSH2_API void libssh2_sftp_seek(LIBSSH2_SFTP_HANDLE *handle, size_t offset); 274LIBSSH2_API void libssh2_sftp_seek64(LIBSSH2_SFTP_HANDLE *handle, 275 libssh2_uint64_t offset); 276#define libssh2_sftp_rewind(handle) libssh2_sftp_seek64((handle), 0) 277 278LIBSSH2_API size_t libssh2_sftp_tell(LIBSSH2_SFTP_HANDLE *handle); 279LIBSSH2_API libssh2_uint64_t libssh2_sftp_tell64(LIBSSH2_SFTP_HANDLE *handle); 280 281LIBSSH2_API int libssh2_sftp_fstat_ex(LIBSSH2_SFTP_HANDLE *handle, 282 LIBSSH2_SFTP_ATTRIBUTES *attrs, 283 int setstat); 284#define libssh2_sftp_fstat(handle, attrs) \ 285 libssh2_sftp_fstat_ex((handle), (attrs), 0) 286#define libssh2_sftp_fsetstat(handle, attrs) \ 287 libssh2_sftp_fstat_ex((handle), (attrs), 1) 288 289/* Miscellaneous Ops */ 290LIBSSH2_API int libssh2_sftp_rename_ex(LIBSSH2_SFTP *sftp, 291 const char *source_filename, 292 unsigned int srouce_filename_len, 293 const char *dest_filename, 294 unsigned int dest_filename_len, 295 long flags); 296#define libssh2_sftp_rename(sftp, sourcefile, destfile) \ 297 libssh2_sftp_rename_ex((sftp), \ 298 (sourcefile), (unsigned int)strlen(sourcefile), \ 299 (destfile), (unsigned int)strlen(destfile), \ 300 LIBSSH2_SFTP_RENAME_OVERWRITE | \ 301 LIBSSH2_SFTP_RENAME_ATOMIC | \ 302 LIBSSH2_SFTP_RENAME_NATIVE) 303 304LIBSSH2_API int libssh2_sftp_unlink_ex(LIBSSH2_SFTP *sftp, 305 const char *filename, 306 unsigned int filename_len); 307#define libssh2_sftp_unlink(sftp, filename) \ 308 libssh2_sftp_unlink_ex((sftp), (filename), strlen(filename)) 309 310LIBSSH2_API int libssh2_sftp_fstatvfs(LIBSSH2_SFTP_HANDLE *handle, 311 LIBSSH2_SFTP_STATVFS *st); 312 313LIBSSH2_API int libssh2_sftp_statvfs(LIBSSH2_SFTP *sftp, 314 const char *path, 315 size_t path_len, 316 LIBSSH2_SFTP_STATVFS *st); 317 318LIBSSH2_API int libssh2_sftp_mkdir_ex(LIBSSH2_SFTP *sftp, 319 const char *path, 320 unsigned int path_len, long mode); 321#define libssh2_sftp_mkdir(sftp, path, mode) \ 322 libssh2_sftp_mkdir_ex((sftp), (path), (unsigned int)strlen(path), (mode)) 323 324LIBSSH2_API int libssh2_sftp_rmdir_ex(LIBSSH2_SFTP *sftp, 325 const char *path, 326 unsigned int path_len); 327#define libssh2_sftp_rmdir(sftp, path) \ 328 libssh2_sftp_rmdir_ex((sftp), (path), (unsigned int)strlen(path)) 329 330LIBSSH2_API int libssh2_sftp_stat_ex(LIBSSH2_SFTP *sftp, 331 const char *path, 332 unsigned int path_len, 333 int stat_type, 334 LIBSSH2_SFTP_ATTRIBUTES *attrs); 335#define libssh2_sftp_stat(sftp, path, attrs) \ 336 libssh2_sftp_stat_ex((sftp), (path), (unsigned int)strlen(path), \ 337 LIBSSH2_SFTP_STAT, (attrs)) 338#define libssh2_sftp_lstat(sftp, path, attrs) \ 339 libssh2_sftp_stat_ex((sftp), (path), (unsigned int)strlen(path), \ 340 LIBSSH2_SFTP_LSTAT, (attrs)) 341#define libssh2_sftp_setstat(sftp, path, attrs) \ 342 libssh2_sftp_stat_ex((sftp), (path), (unsigned int)strlen(path), \ 343 LIBSSH2_SFTP_SETSTAT, (attrs)) 344 345LIBSSH2_API int libssh2_sftp_symlink_ex(LIBSSH2_SFTP *sftp, 346 const char *path, 347 unsigned int path_len, 348 char *target, 349 unsigned int target_len, 350 int link_type); 351#define libssh2_sftp_symlink(sftp, orig, linkpath) \ 352 libssh2_sftp_symlink_ex((sftp), \ 353 (orig), (unsigned int)strlen(orig), \ 354 (linkpath), (unsigned int)strlen(linkpath), \ 355 LIBSSH2_SFTP_SYMLINK) 356#define libssh2_sftp_readlink(sftp, path, target, maxlen) \ 357 libssh2_sftp_symlink_ex((sftp), \ 358 (path), (unsigned int)strlen(path), \ 359 (target), (maxlen), \ 360 LIBSSH2_SFTP_READLINK) 361#define libssh2_sftp_realpath(sftp, path, target, maxlen) \ 362 libssh2_sftp_symlink_ex((sftp), \ 363 (path), (unsigned int)strlen(path), \ 364 (target), (maxlen), \ 365 LIBSSH2_SFTP_REALPATH) 366 367#ifdef __cplusplus 368} /* extern "C" */ 369#endif 370 371#endif /* LIBSSH2_SFTP_H */