source/include/libssh2_sftp.h

0001 /* Copyright (C) Sara Golemon <sarag@libssh2.org>
0002  * All rights reserved.
0003  *
0004  * Redistribution and use in source and binary forms,
0005  * with or without modification, are permitted provided
0006  * that the following conditions are met:
0007  *
0008  *   Redistributions of source code must retain the above
0009  *   copyright notice, this list of conditions and the
0010  *   following disclaimer.
0011  *
0012  *   Redistributions in binary form must reproduce the above
0013  *   copyright notice, this list of conditions and the following
0014  *   disclaimer in the documentation and/or other materials
0015  *   provided with the distribution.
0016  *
0017  *   Neither the name of the copyright holder nor the names
0018  *   of any other contributors may be used to endorse or
0019  *   promote products derived from this software without
0020  *   specific prior written permission.
0021  *
0022  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
0023  * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
0024  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
0025  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0026  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
0027  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
0028  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
0029  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
0030  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0031  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
0032  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
0033  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
0034  * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
0035  * OF SUCH DAMAGE.
0036  *
0037  * SPDX-License-Identifier: BSD-3-Clause
0038  */
0039
0040 #ifndef LIBSSH2_SFTP_H
0041 #define LIBSSH2_SFTP_H 1
0042
0043 #include "libssh2.h"
0044
0045 #ifndef _WIN32
0046 #include <unistd.h>
0047 #endif
0048
0049 #ifdef __cplusplus
0050 extern "C" {
0051 #endif
0052
0053 /* Note: Version 6 was documented at the time of writing
0054  * However it was marked as "DO NOT IMPLEMENT" due to pending changes
0055  *
0056  * Let's start with Version 3 (The version found in OpenSSH) and go from there
0057  */
0058 #define LIBSSH2_SFTP_VERSION        3
0059
0060 typedef struct _LIBSSH2_SFTP                LIBSSH2_SFTP;
0061 typedef struct _LIBSSH2_SFTP_HANDLE         LIBSSH2_SFTP_HANDLE;
0062 typedef struct _LIBSSH2_SFTP_ATTRIBUTES     LIBSSH2_SFTP_ATTRIBUTES;
0063 typedef struct _LIBSSH2_SFTP_STATVFS        LIBSSH2_SFTP_STATVFS;
0064
0065 /* Flags for open_ex() */
0066 #define LIBSSH2_SFTP_OPENFILE           0
0067 #define LIBSSH2_SFTP_OPENDIR            1
0068
0069 /* Flags for rename_ex() */
0070 #define LIBSSH2_SFTP_RENAME_OVERWRITE   0x00000001
0071 #define LIBSSH2_SFTP_RENAME_ATOMIC      0x00000002
0072 #define LIBSSH2_SFTP_RENAME_NATIVE      0x00000004
0073
0074 /* Flags for stat_ex() */
0075 #define LIBSSH2_SFTP_STAT               0
0076 #define LIBSSH2_SFTP_LSTAT              1
0077 #define LIBSSH2_SFTP_SETSTAT            2
0078
0079 /* Flags for symlink_ex() */
0080 #define LIBSSH2_SFTP_SYMLINK            0
0081 #define LIBSSH2_SFTP_READLINK           1
0082 #define LIBSSH2_SFTP_REALPATH           2
0083
0084 /* Flags for sftp_mkdir() */
0085 #define LIBSSH2_SFTP_DEFAULT_MODE      -1
0086
0087 /* SFTP attribute flag bits */
0088 #define LIBSSH2_SFTP_ATTR_SIZE              0x00000001
0089 #define LIBSSH2_SFTP_ATTR_UIDGID            0x00000002
0090 #define LIBSSH2_SFTP_ATTR_PERMISSIONS       0x00000004
0091 #define LIBSSH2_SFTP_ATTR_ACMODTIME         0x00000008
0092 #define LIBSSH2_SFTP_ATTR_EXTENDED          0x80000000
0093
0094 /* SFTP statvfs flag bits */
0095 #define LIBSSH2_SFTP_ST_RDONLY              0x00000001
0096 #define LIBSSH2_SFTP_ST_NOSUID              0x00000002
0097
0098 struct _LIBSSH2_SFTP_ATTRIBUTES {
0099     /* If flags & ATTR_* bit is set, then the value in this struct will be
0100      * meaningful Otherwise it should be ignored
0101      */
0102     unsigned long flags;
0103
0104     libssh2_uint64_t filesize;
0105     unsigned long uid, gid;
0106     unsigned long permissions;
0107     unsigned long atime, mtime;
0108 };
0109
0110 struct _LIBSSH2_SFTP_STATVFS {
0111     libssh2_uint64_t  f_bsize;    /* file system block size */
0112     libssh2_uint64_t  f_frsize;   /* fragment size */
0113     libssh2_uint64_t  f_blocks;   /* size of fs in f_frsize units */
0114     libssh2_uint64_t  f_bfree;    /* # free blocks */
0115     libssh2_uint64_t  f_bavail;   /* # free blocks for non-root */
0116     libssh2_uint64_t  f_files;    /* # inodes */
0117     libssh2_uint64_t  f_ffree;    /* # free inodes */
0118     libssh2_uint64_t  f_favail;   /* # free inodes for non-root */
0119     libssh2_uint64_t  f_fsid;     /* file system ID */
0120     libssh2_uint64_t  f_flag;     /* mount flags */
0121     libssh2_uint64_t  f_namemax;  /* maximum filename length */
0122 };
0123
0124 /* SFTP filetypes */
0125 #define LIBSSH2_SFTP_TYPE_REGULAR           1
0126 #define LIBSSH2_SFTP_TYPE_DIRECTORY         2
0127 #define LIBSSH2_SFTP_TYPE_SYMLINK           3
0128 #define LIBSSH2_SFTP_TYPE_SPECIAL           4
0129 #define LIBSSH2_SFTP_TYPE_UNKNOWN           5
0130 #define LIBSSH2_SFTP_TYPE_SOCKET            6
0131 #define LIBSSH2_SFTP_TYPE_CHAR_DEVICE       7
0132 #define LIBSSH2_SFTP_TYPE_BLOCK_DEVICE      8
0133 #define LIBSSH2_SFTP_TYPE_FIFO              9
0134
0135 /*
0136  * Reproduce the POSIX file modes here for systems that are not POSIX
0137  * compliant.
0138  *
0139  * These is used in "permissions" of "struct _LIBSSH2_SFTP_ATTRIBUTES"
0140  */
0141 /* File type */
0142 #define LIBSSH2_SFTP_S_IFMT         0170000     /* type of file mask */
0143 #define LIBSSH2_SFTP_S_IFIFO        0010000     /* named pipe (fifo) */
0144 #define LIBSSH2_SFTP_S_IFCHR        0020000     /* character special */
0145 #define LIBSSH2_SFTP_S_IFDIR        0040000     /* directory */
0146 #define LIBSSH2_SFTP_S_IFBLK        0060000     /* block special */
0147 #define LIBSSH2_SFTP_S_IFREG        0100000     /* regular */
0148 #define LIBSSH2_SFTP_S_IFLNK        0120000     /* symbolic link */
0149 #define LIBSSH2_SFTP_S_IFSOCK       0140000     /* socket */
0150
0151 /* File mode */
0152 /* Read, write, execute/search by owner */
0153 #define LIBSSH2_SFTP_S_IRWXU        0000700     /* RWX mask for owner */
0154 #define LIBSSH2_SFTP_S_IRUSR        0000400     /* R for owner */
0155 #define LIBSSH2_SFTP_S_IWUSR        0000200     /* W for owner */
0156 #define LIBSSH2_SFTP_S_IXUSR        0000100     /* X for owner */
0157 /* Read, write, execute/search by group */
0158 #define LIBSSH2_SFTP_S_IRWXG        0000070     /* RWX mask for group */
0159 #define LIBSSH2_SFTP_S_IRGRP        0000040     /* R for group */
0160 #define LIBSSH2_SFTP_S_IWGRP        0000020     /* W for group */
0161 #define LIBSSH2_SFTP_S_IXGRP        0000010     /* X for group */
0162 /* Read, write, execute/search by others */
0163 #define LIBSSH2_SFTP_S_IRWXO        0000007     /* RWX mask for other */
0164 #define LIBSSH2_SFTP_S_IROTH        0000004     /* R for other */
0165 #define LIBSSH2_SFTP_S_IWOTH        0000002     /* W for other */
0166 #define LIBSSH2_SFTP_S_IXOTH        0000001     /* X for other */
0167
0168 /* macros to check for specific file types, added in 1.2.5 */
0169 #define LIBSSH2_SFTP_S_ISLNK(m) \
0170     (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFLNK)
0171 #define LIBSSH2_SFTP_S_ISREG(m) \
0172     (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFREG)
0173 #define LIBSSH2_SFTP_S_ISDIR(m) \
0174     (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFDIR)
0175 #define LIBSSH2_SFTP_S_ISCHR(m) \
0176     (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFCHR)
0177 #define LIBSSH2_SFTP_S_ISBLK(m) \
0178     (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFBLK)
0179 #define LIBSSH2_SFTP_S_ISFIFO(m) \
0180     (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFIFO)
0181 #define LIBSSH2_SFTP_S_ISSOCK(m) \
0182     (((m) & LIBSSH2_SFTP_S_IFMT) == LIBSSH2_SFTP_S_IFSOCK)
0183
0184 /* SFTP File Transfer Flags -- (e.g. flags parameter to sftp_open())
0185  * Danger will robinson... APPEND doesn't have any effect on OpenSSH servers */
0186 #define LIBSSH2_FXF_READ                        0x00000001
0187 #define LIBSSH2_FXF_WRITE                       0x00000002
0188 #define LIBSSH2_FXF_APPEND                      0x00000004
0189 #define LIBSSH2_FXF_CREAT                       0x00000008
0190 #define LIBSSH2_FXF_TRUNC                       0x00000010
0191 #define LIBSSH2_FXF_EXCL                        0x00000020
0192
0193 /* SFTP Status Codes (returned by libssh2_sftp_last_error() ) */
0194 #define LIBSSH2_FX_OK                       0UL
0195 #define LIBSSH2_FX_EOF                      1UL
0196 #define LIBSSH2_FX_NO_SUCH_FILE             2UL
0197 #define LIBSSH2_FX_PERMISSION_DENIED        3UL
0198 #define LIBSSH2_FX_FAILURE                  4UL
0199 #define LIBSSH2_FX_BAD_MESSAGE              5UL
0200 #define LIBSSH2_FX_NO_CONNECTION            6UL
0201 #define LIBSSH2_FX_CONNECTION_LOST          7UL
0202 #define LIBSSH2_FX_OP_UNSUPPORTED           8UL
0203 #define LIBSSH2_FX_INVALID_HANDLE           9UL
0204 #define LIBSSH2_FX_NO_SUCH_PATH             10UL
0205 #define LIBSSH2_FX_FILE_ALREADY_EXISTS      11UL
0206 #define LIBSSH2_FX_WRITE_PROTECT            12UL
0207 #define LIBSSH2_FX_NO_MEDIA                 13UL
0208 #define LIBSSH2_FX_NO_SPACE_ON_FILESYSTEM   14UL
0209 #define LIBSSH2_FX_QUOTA_EXCEEDED           15UL
0210 #define LIBSSH2_FX_UNKNOWN_PRINCIPLE        16UL /* Initial mis-spelling */
0211 #define LIBSSH2_FX_UNKNOWN_PRINCIPAL        16UL
0212 #define LIBSSH2_FX_LOCK_CONFlICT            17UL /* Initial mis-spelling */
0213 #define LIBSSH2_FX_LOCK_CONFLICT            17UL
0214 #define LIBSSH2_FX_DIR_NOT_EMPTY            18UL
0215 #define LIBSSH2_FX_NOT_A_DIRECTORY          19UL
0216 #define LIBSSH2_FX_INVALID_FILENAME         20UL
0217 #define LIBSSH2_FX_LINK_LOOP                21UL
0218
0219 /* Returned by any function that would block during a read/write operation */
0220 #define LIBSSH2SFTP_EAGAIN LIBSSH2_ERROR_EAGAIN
0221
0222 /* SFTP API */
0223 LIBSSH2_API LIBSSH2_SFTP *libssh2_sftp_init(LIBSSH2_SESSION *session);
0224 LIBSSH2_API int libssh2_sftp_shutdown(LIBSSH2_SFTP *sftp);
0225 LIBSSH2_API unsigned long libssh2_sftp_last_error(LIBSSH2_SFTP *sftp);
0226 LIBSSH2_API LIBSSH2_CHANNEL *libssh2_sftp_get_channel(LIBSSH2_SFTP *sftp);
0227
0228 /* File / Directory Ops */
0229 LIBSSH2_API LIBSSH2_SFTP_HANDLE *
0230 libssh2_sftp_open_ex(LIBSSH2_SFTP *sftp,
0231                      const char *filename,
0232                      unsigned int filename_len,
0233                      unsigned long flags,
0234                      long mode, int open_type);
0235 #define libssh2_sftp_open(sftp, filename, flags, mode) \
0236     libssh2_sftp_open_ex((sftp), \
0237                          (filename), (unsigned int)strlen(filename), \
0238                          (flags), (mode), LIBSSH2_SFTP_OPENFILE)
0239 #define libssh2_sftp_opendir(sftp, path) \
0240     libssh2_sftp_open_ex((sftp), \
0241                          (path), (unsigned int)strlen(path), \
0242                          0, 0, LIBSSH2_SFTP_OPENDIR)
0243 LIBSSH2_API LIBSSH2_SFTP_HANDLE *
0244 libssh2_sftp_open_ex_r(LIBSSH2_SFTP *sftp,
0245                        const char *filename,
0246                        size_t filename_len,
0247                        unsigned long flags,
0248                        long mode, int open_type,
0249                        LIBSSH2_SFTP_ATTRIBUTES *attrs);
0250 #define libssh2_sftp_open_r(sftp, filename, flags, mode, attrs) \
0251     libssh2_sftp_open_ex_r((sftp), (filename), strlen(filename), \
0252                            (flags), (mode), LIBSSH2_SFTP_OPENFILE, \
0253                            (attrs))
0254
0255 LIBSSH2_API ssize_t libssh2_sftp_read(LIBSSH2_SFTP_HANDLE *handle,
0256                                       char *buffer, size_t buffer_maxlen);
0257
0258 LIBSSH2_API int libssh2_sftp_readdir_ex(LIBSSH2_SFTP_HANDLE *handle, \
0259                                         char *buffer, size_t buffer_maxlen,
0260                                         char *longentry,
0261                                         size_t longentry_maxlen,
0262                                         LIBSSH2_SFTP_ATTRIBUTES *attrs);
0263 #define libssh2_sftp_readdir(handle, buffer, buffer_maxlen, attrs) \
0264     libssh2_sftp_readdir_ex((handle), (buffer), (buffer_maxlen), NULL, 0, \
0265                             (attrs))
0266
0267 LIBSSH2_API ssize_t libssh2_sftp_write(LIBSSH2_SFTP_HANDLE *handle,
0268                                        const char *buffer, size_t count);
0269 LIBSSH2_API int libssh2_sftp_fsync(LIBSSH2_SFTP_HANDLE *handle);
0270
0271 LIBSSH2_API int libssh2_sftp_close_handle(LIBSSH2_SFTP_HANDLE *handle);
0272 #define libssh2_sftp_close(handle) libssh2_sftp_close_handle(handle)
0273 #define libssh2_sftp_closedir(handle) libssh2_sftp_close_handle(handle)
0274
0275 LIBSSH2_API void libssh2_sftp_seek(LIBSSH2_SFTP_HANDLE *handle, size_t offset);
0276 LIBSSH2_API void libssh2_sftp_seek64(LIBSSH2_SFTP_HANDLE *handle,
0277                                      libssh2_uint64_t offset);
0278 #define libssh2_sftp_rewind(handle) libssh2_sftp_seek64((handle), 0)
0279
0280 LIBSSH2_API size_t libssh2_sftp_tell(LIBSSH2_SFTP_HANDLE *handle);
0281 LIBSSH2_API libssh2_uint64_t libssh2_sftp_tell64(LIBSSH2_SFTP_HANDLE *handle);
0282
0283 LIBSSH2_API int libssh2_sftp_fstat_ex(LIBSSH2_SFTP_HANDLE *handle,
0284                                       LIBSSH2_SFTP_ATTRIBUTES *attrs,
0285                                       int setstat);
0286 #define libssh2_sftp_fstat(handle, attrs) \
0287     libssh2_sftp_fstat_ex((handle), (attrs), 0)
0288 #define libssh2_sftp_fsetstat(handle, attrs) \
0289     libssh2_sftp_fstat_ex((handle), (attrs), 1)
0290
0291 /* Miscellaneous Ops */
0292 LIBSSH2_API int libssh2_sftp_rename_ex(LIBSSH2_SFTP *sftp,
0293                                        const char *source_filename,
0294                                        unsigned int srouce_filename_len,
0295                                        const char *dest_filename,
0296                                        unsigned int dest_filename_len,
0297                                        long flags);
0298 #define libssh2_sftp_rename(sftp, sourcefile, destfile) \
0299     libssh2_sftp_rename_ex((sftp), \
0300                            (sourcefile), (unsigned int)strlen(sourcefile), \
0301                            (destfile), (unsigned int)strlen(destfile), \
0302                            LIBSSH2_SFTP_RENAME_OVERWRITE | \
0303                            LIBSSH2_SFTP_RENAME_ATOMIC | \
0304                            LIBSSH2_SFTP_RENAME_NATIVE)
0305
0306 LIBSSH2_API int libssh2_sftp_posix_rename_ex(LIBSSH2_SFTP *sftp,
0307                                              const char *source_filename,
0308                                              size_t srouce_filename_len,
0309                                              const char *dest_filename,
0310                                              size_t dest_filename_len);
0311 #define libssh2_sftp_posix_rename(sftp, sourcefile, destfile) \
0312     libssh2_sftp_posix_rename_ex((sftp), (sourcefile), strlen(sourcefile), \
0313                                  (destfile), strlen(destfile))
0314
0315 LIBSSH2_API int libssh2_sftp_unlink_ex(LIBSSH2_SFTP *sftp,
0316                                        const char *filename,
0317                                        unsigned int filename_len);
0318 #define libssh2_sftp_unlink(sftp, filename) \
0319     libssh2_sftp_unlink_ex((sftp), (filename), (unsigned int)strlen(filename))
0320
0321 LIBSSH2_API int libssh2_sftp_fstatvfs(LIBSSH2_SFTP_HANDLE *handle,
0322                                       LIBSSH2_SFTP_STATVFS *st);
0323
0324 LIBSSH2_API int libssh2_sftp_statvfs(LIBSSH2_SFTP *sftp,
0325                                      const char *path,
0326                                      size_t path_len,
0327                                      LIBSSH2_SFTP_STATVFS *st);
0328
0329 LIBSSH2_API int libssh2_sftp_mkdir_ex(LIBSSH2_SFTP *sftp,
0330                                       const char *path,
0331                                       unsigned int path_len, long mode);
0332 #define libssh2_sftp_mkdir(sftp, path, mode) \
0333     libssh2_sftp_mkdir_ex((sftp), (path), (unsigned int)strlen(path), (mode))
0334
0335 LIBSSH2_API int libssh2_sftp_rmdir_ex(LIBSSH2_SFTP *sftp,
0336                                       const char *path,
0337                                       unsigned int path_len);
0338 #define libssh2_sftp_rmdir(sftp, path) \
0339     libssh2_sftp_rmdir_ex((sftp), (path), (unsigned int)strlen(path))
0340
0341 LIBSSH2_API int libssh2_sftp_stat_ex(LIBSSH2_SFTP *sftp,
0342                                      const char *path,
0343                                      unsigned int path_len,
0344                                      int stat_type,
0345                                      LIBSSH2_SFTP_ATTRIBUTES *attrs);
0346 #define libssh2_sftp_stat(sftp, path, attrs) \
0347     libssh2_sftp_stat_ex((sftp), (path), (unsigned int)strlen(path), \
0348                          LIBSSH2_SFTP_STAT, (attrs))
0349 #define libssh2_sftp_lstat(sftp, path, attrs) \
0350     libssh2_sftp_stat_ex((sftp), (path), (unsigned int)strlen(path), \
0351                          LIBSSH2_SFTP_LSTAT, (attrs))
0352 #define libssh2_sftp_setstat(sftp, path, attrs) \
0353     libssh2_sftp_stat_ex((sftp), (path), (unsigned int)strlen(path), \
0354                          LIBSSH2_SFTP_SETSTAT, (attrs))
0355
0356 LIBSSH2_API int libssh2_sftp_symlink_ex(LIBSSH2_SFTP *sftp,
0357                                         const char *path,
0358                                         unsigned int path_len,
0359                                         char *target,
0360                                         unsigned int target_len,
0361                                         int link_type);
0362 #define libssh2_sftp_symlink(sftp, orig, linkpath) \
0363     libssh2_sftp_symlink_ex((sftp), \
0364                             (orig), (unsigned int)strlen(orig), \
0365                             (linkpath), (unsigned int)strlen(linkpath), \
0366                             LIBSSH2_SFTP_SYMLINK)
0367 #define libssh2_sftp_readlink(sftp, path, target, maxlen) \
0368     libssh2_sftp_symlink_ex((sftp), \
0369                             (path), (unsigned int)strlen(path), \
0370                             (target), (maxlen), \
0371                             LIBSSH2_SFTP_READLINK)
0372 #define libssh2_sftp_realpath(sftp, path, target, maxlen) \
0373     libssh2_sftp_symlink_ex((sftp), \
0374                             (path), (unsigned int)strlen(path), \
0375                             (target), (maxlen), \
0376                             LIBSSH2_SFTP_REALPATH)
0377
0378 #ifdef __cplusplus
0379 } /* extern "C" */
0380 #endif
0381
0382 #endif /* LIBSSH2_SFTP_H */