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