1 /* Copyright (c) 2004-2007, Sara Golemon <sarag@libssh2.org>
4 * Redistribution and use in source and binary forms,
5 * with or without modification, are permitted provided
6 * that the following conditions are met:
8 * Redistributions of source code must retain the above
9 * copyright notice, this list of conditions and the
10 * following disclaimer.
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.
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.
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
38 #ifndef LIBSSH2_SFTP_H
39 #define LIBSSH2_SFTP_H 1
49 /* Note: Version 6 was documented at the time of writing
50 * However it was marked as "DO NOT IMPLEMENT" due to pending changes
52 * Let's start with Version 3 (The version found in OpenSSH) and go from there
54 #define LIBSSH2_SFTP_VERSION 3
55 #define LIBSSH2_SFTP_PACKET_MAXLEN 40000
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
;
61 /* Flags for open_ex() */
62 #define LIBSSH2_SFTP_OPENFILE 0
63 #define LIBSSH2_SFTP_OPENDIR 1
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
70 /* Flags for stat_ex() */
71 #define LIBSSH2_SFTP_STAT 0
72 #define LIBSSH2_SFTP_LSTAT 1
73 #define LIBSSH2_SFTP_SETSTAT 2
75 /* Flags for symlink_ex() */
76 #define LIBSSH2_SFTP_SYMLINK 0
77 #define LIBSSH2_SFTP_READLINK 1
78 #define LIBSSH2_SFTP_REALPATH 2
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
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
93 libssh2_uint64_t filesize
;
94 unsigned long uid
, gid
;
95 unsigned long permissions
;
96 unsigned long atime
, mtime
;
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
111 * Reproduce the POSIX file modes here for systems that are not
114 * These is used in "permissions" of "struct _LIBSSH2_SFTP_ATTRIBUTES"
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 */
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 */
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
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
178 /* Returned by any function that would block during a read/write opperation */
179 #define LIBSSH2SFTP_EAGAIN LIBSSH2_ERROR_EAGAIN
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
);
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)
194 LIBSSH2_API ssize_t
libssh2_sftp_read(LIBSSH2_SFTP_HANDLE
*handle
, char *buffer
, size_t buffer_maxlen
);
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))
202 LIBSSH2_API ssize_t
libssh2_sftp_write(LIBSSH2_SFTP_HANDLE
*handle
, const char *buffer
, size_t count
);
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)
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)
211 LIBSSH2_API
size_t libssh2_sftp_tell(LIBSSH2_SFTP_HANDLE
*handle
);
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)
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
,
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)
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))
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))
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))
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))
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)
249 #endif /* LIBSSH2_SFTP_H */