libssh  0.5.4
sftp.h
Go to the documentation of this file.
1 /*
2  * This file is part of the SSH Library
3  *
4  * Copyright (c) 2003-2008 by Aris Adamantiadis
5  *
6  * The SSH Library is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU Lesser General Public License as published by
8  * the Free Software Foundation; either version 2.1 of the License, or (at your
9  * option) any later version.
10  *
11  * The SSH Library is distributed in the hope that it will be useful, but
12  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
14  * License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public License
17  * along with the SSH Library; see the file COPYING. If not, write to
18  * the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
19  * MA 02111-1307, USA.
20  */
21 
39 #ifndef SFTP_H
40 #define SFTP_H
41 
42 #include <sys/types.h>
43 
44 #include "libssh.h"
45 
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
49 
50 #ifdef _WIN32
51 #ifndef uid_t
52  typedef uint32_t uid_t;
53 #endif /* uid_t */
54 #ifndef gid_t
55  typedef uint32_t gid_t;
56 #endif /* gid_t */
57 #ifdef _MSC_VER
58 #ifndef ssize_t
59  typedef _W64 SSIZE_T ssize_t;
60 #endif /* ssize_t */
61 #endif /* _MSC_VER */
62 #endif /* _WIN32 */
63 
64 typedef struct sftp_attributes_struct* sftp_attributes;
65 typedef struct sftp_client_message_struct* sftp_client_message;
66 typedef struct sftp_dir_struct* sftp_dir;
67 typedef struct sftp_ext_struct *sftp_ext;
68 typedef struct sftp_file_struct* sftp_file;
69 typedef struct sftp_message_struct* sftp_message;
70 typedef struct sftp_packet_struct* sftp_packet;
71 typedef struct sftp_request_queue_struct* sftp_request_queue;
72 typedef struct sftp_session_struct* sftp_session;
73 typedef struct sftp_status_message_struct* sftp_status_message;
74 typedef struct sftp_statvfs_struct* sftp_statvfs_t;
75 
76 struct sftp_session_struct {
77  ssh_session session;
78  ssh_channel channel;
79  int server_version;
80  int client_version;
81  int version;
82  sftp_request_queue queue;
83  uint32_t id_counter;
84  int errnum;
85  void **handles;
86  sftp_ext ext;
87 };
88 
89 struct sftp_packet_struct {
90  sftp_session sftp;
91  uint8_t type;
92  ssh_buffer payload;
93 };
94 
95 /* file handler */
96 struct sftp_file_struct {
97  sftp_session sftp;
98  char *name;
99  uint64_t offset;
100  ssh_string handle;
101  int eof;
102  int nonblocking;
103 };
104 
105 struct sftp_dir_struct {
106  sftp_session sftp;
107  char *name;
108  ssh_string handle; /* handle to directory */
109  ssh_buffer buffer; /* contains raw attributes from server which haven't been parsed */
110  uint32_t count; /* counts the number of following attributes structures into buffer */
111  int eof; /* end of directory listing */
112 };
113 
114 struct sftp_message_struct {
115  sftp_session sftp;
116  uint8_t packet_type;
117  ssh_buffer payload;
118  uint32_t id;
119 };
120 
121 /* this is a bunch of all data that could be into a message */
122 struct sftp_client_message_struct {
123  sftp_session sftp;
124  uint8_t type;
125  uint32_t id;
126  char *filename; /* can be "path" */
127  uint32_t flags;
128  sftp_attributes attr;
129  ssh_string handle;
130  uint64_t offset;
131  uint32_t len;
132  int attr_num;
133  ssh_buffer attrbuf; /* used by sftp_reply_attrs */
134  ssh_string data; /* can be newpath of rename() */
135 };
136 
137 struct sftp_request_queue_struct {
138  sftp_request_queue next;
139  sftp_message message;
140 };
141 
142 /* SSH_FXP_MESSAGE described into .7 page 26 */
143 struct sftp_status_message_struct {
144  uint32_t id;
145  uint32_t status;
146  ssh_string error;
147  ssh_string lang;
148  char *errormsg;
149  char *langmsg;
150 };
151 
152 struct sftp_attributes_struct {
153  char *name;
154  char *longname; /* ls -l output on openssh, not reliable else */
155  uint32_t flags;
156  uint8_t type;
157  uint64_t size;
158  uint32_t uid;
159  uint32_t gid;
160  char *owner; /* set if openssh and version 4 */
161  char *group; /* set if openssh and version 4 */
162  uint32_t permissions;
163  uint64_t atime64;
164  uint32_t atime;
165  uint32_t atime_nseconds;
166  uint64_t createtime;
167  uint32_t createtime_nseconds;
168  uint64_t mtime64;
169  uint32_t mtime;
170  uint32_t mtime_nseconds;
171  ssh_string acl;
172  uint32_t extended_count;
173  ssh_string extended_type;
174  ssh_string extended_data;
175 };
176 
177 struct sftp_statvfs_struct {
178  uint64_t f_bsize; /* file system block size */
179  uint64_t f_frsize; /* fundamental fs block size */
180  uint64_t f_blocks; /* number of blocks (unit f_frsize) */
181  uint64_t f_bfree; /* free blocks in file system */
182  uint64_t f_bavail; /* free blocks for non-root */
183  uint64_t f_files; /* total file inodes */
184  uint64_t f_ffree; /* free file inodes */
185  uint64_t f_favail; /* free file inodes for to non-root */
186  uint64_t f_fsid; /* file system id */
187  uint64_t f_flag; /* bit mask of f_flag values */
188  uint64_t f_namemax; /* maximum filename length */
189 };
190 
191 #define LIBSFTP_VERSION 3
192 
200 LIBSSH_API sftp_session sftp_new(ssh_session session);
201 
207 LIBSSH_API void sftp_free(sftp_session sftp);
208 
216 LIBSSH_API int sftp_init(sftp_session sftp);
217 
228 LIBSSH_API int sftp_get_error(sftp_session sftp);
229 
238 LIBSSH_API unsigned int sftp_extensions_get_count(sftp_session sftp);
239 
249 LIBSSH_API const char *sftp_extensions_get_name(sftp_session sftp, unsigned int indexn);
250 
262 LIBSSH_API const char *sftp_extensions_get_data(sftp_session sftp, unsigned int indexn);
263 
281 LIBSSH_API int sftp_extension_supported(sftp_session sftp, const char *name,
282  const char *data);
283 
296 LIBSSH_API sftp_dir sftp_opendir(sftp_session session, const char *path);
297 
311 LIBSSH_API sftp_attributes sftp_readdir(sftp_session session, sftp_dir dir);
312 
322 LIBSSH_API int sftp_dir_eof(sftp_dir dir);
323 
334 LIBSSH_API sftp_attributes sftp_stat(sftp_session session, const char *path);
335 
349 LIBSSH_API sftp_attributes sftp_lstat(sftp_session session, const char *path);
350 
359 LIBSSH_API sftp_attributes sftp_fstat(sftp_file file);
360 
366 LIBSSH_API void sftp_attributes_free(sftp_attributes file);
367 
375 LIBSSH_API int sftp_closedir(sftp_dir dir);
376 
386 LIBSSH_API int sftp_close(sftp_file file);
387 
414 LIBSSH_API sftp_file sftp_open(sftp_session session, const char *file, int accesstype,
415  mode_t mode);
416 
417 LIBSSH_API void sftp_file_set_nonblocking(sftp_file handle);
418 
419 LIBSSH_API void sftp_file_set_blocking(sftp_file handle);
420 
433 LIBSSH_API ssize_t sftp_read(sftp_file file, void *buf, size_t count);
434 
466 LIBSSH_API int sftp_async_read_begin(sftp_file file, uint32_t len);
467 
491 LIBSSH_API int sftp_async_read(sftp_file file, void *data, uint32_t len, uint32_t id);
492 
509 LIBSSH_API ssize_t sftp_write(sftp_file file, const void *buf, size_t count);
510 
520 LIBSSH_API int sftp_seek(sftp_file file, uint32_t new_offset);
521 
532 LIBSSH_API int sftp_seek64(sftp_file file, uint64_t new_offset);
533 
543 LIBSSH_API unsigned long sftp_tell(sftp_file file);
544 
554 LIBSSH_API uint64_t sftp_tell64(sftp_file file);
555 
562 LIBSSH_API void sftp_rewind(sftp_file file);
563 
573 LIBSSH_API int sftp_unlink(sftp_session sftp, const char *file);
574 
584 LIBSSH_API int sftp_rmdir(sftp_session sftp, const char *directory);
585 
599 LIBSSH_API int sftp_mkdir(sftp_session sftp, const char *directory, mode_t mode);
600 
614 LIBSSH_API int sftp_rename(sftp_session sftp, const char *original, const char *newname);
615 
628 LIBSSH_API int sftp_setstat(sftp_session sftp, const char *file, sftp_attributes attr);
629 
643 LIBSSH_API int sftp_chown(sftp_session sftp, const char *file, uid_t owner, gid_t group);
644 
658 LIBSSH_API int sftp_chmod(sftp_session sftp, const char *file, mode_t mode);
659 
672 LIBSSH_API int sftp_utimes(sftp_session sftp, const char *file, const struct timeval *times);
673 
685 LIBSSH_API int sftp_symlink(sftp_session sftp, const char *target, const char *dest);
686 
696 LIBSSH_API char *sftp_readlink(sftp_session sftp, const char *path);
697 
707 LIBSSH_API sftp_statvfs_t sftp_statvfs(sftp_session sftp, const char *path);
708 
716 LIBSSH_API sftp_statvfs_t sftp_fstatvfs(sftp_file file);
717 
723 LIBSSH_API void sftp_statvfs_free(sftp_statvfs_t statvfs_o);
724 
734 LIBSSH_API char *sftp_canonicalize_path(sftp_session sftp, const char *path);
735 
743 LIBSSH_API int sftp_server_version(sftp_session sftp);
744 
745 #ifdef WITH_SERVER
746 
755 LIBSSH_API sftp_session sftp_server_new(ssh_session session, ssh_channel chan);
756 
764 LIBSSH_API int sftp_server_init(sftp_session sftp);
765 #endif /* WITH_SERVER */
766 
767 /* this is not a public interface */
768 #define SFTP_HANDLES 256
769 sftp_packet sftp_packet_read(sftp_session sftp);
770 int sftp_packet_write(sftp_session sftp,uint8_t type, ssh_buffer payload);
771 void sftp_packet_free(sftp_packet packet);
772 int buffer_add_attributes(ssh_buffer buffer, sftp_attributes attr);
773 sftp_attributes sftp_parse_attr(sftp_session session, ssh_buffer buf,int expectname);
774 /* sftpserver.c */
775 
776 sftp_client_message sftp_get_client_message(sftp_session sftp);
777 void sftp_client_message_free(sftp_client_message msg);
778 int sftp_reply_name(sftp_client_message msg, const char *name,
779  sftp_attributes attr);
780 int sftp_reply_handle(sftp_client_message msg, ssh_string handle);
781 ssh_string sftp_handle_alloc(sftp_session sftp, void *info);
782 int sftp_reply_attr(sftp_client_message msg, sftp_attributes attr);
783 void *sftp_handle(sftp_session sftp, ssh_string handle);
784 int sftp_reply_status(sftp_client_message msg, uint32_t status, const char *message);
785 int sftp_reply_names_add(sftp_client_message msg, const char *file,
786  const char *longname, sftp_attributes attr);
787 int sftp_reply_names(sftp_client_message msg);
788 int sftp_reply_data(sftp_client_message msg, const void *data, int len);
789 void sftp_handle_remove(sftp_session sftp, void *handle);
790 
791 /* SFTP commands and constants */
792 #define SSH_FXP_INIT 1
793 #define SSH_FXP_VERSION 2
794 #define SSH_FXP_OPEN 3
795 #define SSH_FXP_CLOSE 4
796 #define SSH_FXP_READ 5
797 #define SSH_FXP_WRITE 6
798 #define SSH_FXP_LSTAT 7
799 #define SSH_FXP_FSTAT 8
800 #define SSH_FXP_SETSTAT 9
801 #define SSH_FXP_FSETSTAT 10
802 #define SSH_FXP_OPENDIR 11
803 #define SSH_FXP_READDIR 12
804 #define SSH_FXP_REMOVE 13
805 #define SSH_FXP_MKDIR 14
806 #define SSH_FXP_RMDIR 15
807 #define SSH_FXP_REALPATH 16
808 #define SSH_FXP_STAT 17
809 #define SSH_FXP_RENAME 18
810 #define SSH_FXP_READLINK 19
811 #define SSH_FXP_SYMLINK 20
812 
813 #define SSH_FXP_STATUS 101
814 #define SSH_FXP_HANDLE 102
815 #define SSH_FXP_DATA 103
816 #define SSH_FXP_NAME 104
817 #define SSH_FXP_ATTRS 105
818 
819 #define SSH_FXP_EXTENDED 200
820 #define SSH_FXP_EXTENDED_REPLY 201
821 
822 /* attributes */
823 /* sftp draft is completely braindead : version 3 and 4 have different flags for same constants */
824 /* and even worst, version 4 has same flag for 2 different constants */
825 /* follow up : i won't develop any sftp4 compliant library before having a clarification */
826 
827 #define SSH_FILEXFER_ATTR_SIZE 0x00000001
828 #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004
829 #define SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008
830 #define SSH_FILEXFER_ATTR_ACMODTIME 0x00000008
831 #define SSH_FILEXFER_ATTR_CREATETIME 0x00000010
832 #define SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020
833 #define SSH_FILEXFER_ATTR_ACL 0x00000040
834 #define SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080
835 #define SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100
836 #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000
837 #define SSH_FILEXFER_ATTR_UIDGID 0x00000002
838 
839 /* types */
840 #define SSH_FILEXFER_TYPE_REGULAR 1
841 #define SSH_FILEXFER_TYPE_DIRECTORY 2
842 #define SSH_FILEXFER_TYPE_SYMLINK 3
843 #define SSH_FILEXFER_TYPE_SPECIAL 4
844 #define SSH_FILEXFER_TYPE_UNKNOWN 5
845 
854 #define SSH_FX_OK 0
855 
856 #define SSH_FX_EOF 1
857 
858 #define SSH_FX_NO_SUCH_FILE 2
859 
860 #define SSH_FX_PERMISSION_DENIED 3
861 
862 #define SSH_FX_FAILURE 4
863 
864 #define SSH_FX_BAD_MESSAGE 5
865 
866 #define SSH_FX_NO_CONNECTION 6
867 
868 #define SSH_FX_CONNECTION_LOST 7
869 
870 #define SSH_FX_OP_UNSUPPORTED 8
871 
872 #define SSH_FX_INVALID_HANDLE 9
873 
874 #define SSH_FX_NO_SUCH_PATH 10
875 
876 #define SSH_FX_FILE_ALREADY_EXISTS 11
877 
878 #define SSH_FX_WRITE_PROTECT 12
879 
880 #define SSH_FX_NO_MEDIA 13
881 
884 /* file flags */
885 #define SSH_FXF_READ 0x01
886 #define SSH_FXF_WRITE 0x02
887 #define SSH_FXF_APPEND 0x04
888 #define SSH_FXF_CREAT 0x08
889 #define SSH_FXF_TRUNC 0x10
890 #define SSH_FXF_EXCL 0x20
891 #define SSH_FXF_TEXT 0x40
892 
893 /* rename flags */
894 #define SSH_FXF_RENAME_OVERWRITE 0x00000001
895 #define SSH_FXF_RENAME_ATOMIC 0x00000002
896 #define SSH_FXF_RENAME_NATIVE 0x00000004
897 
898 #define SFTP_OPEN SSH_FXP_OPEN
899 #define SFTP_CLOSE SSH_FXP_CLOSE
900 #define SFTP_READ SSH_FXP_READ
901 #define SFTP_WRITE SSH_FXP_WRITE
902 #define SFTP_LSTAT SSH_FXP_LSTAT
903 #define SFTP_FSTAT SSH_FXP_FSTAT
904 #define SFTP_SETSTAT SSH_FXP_SETSTAT
905 #define SFTP_FSETSTAT SSH_FXP_FSETSTAT
906 #define SFTP_OPENDIR SSH_FXP_OPENDIR
907 #define SFTP_READDIR SSH_FXP_READDIR
908 #define SFTP_REMOVE SSH_FXP_REMOVE
909 #define SFTP_MKDIR SSH_FXP_MKDIR
910 #define SFTP_RMDIR SSH_FXP_RMDIR
911 #define SFTP_REALPATH SSH_FXP_REALPATH
912 #define SFTP_STAT SSH_FXP_STAT
913 #define SFTP_RENAME SSH_FXP_RENAME
914 #define SFTP_READLINK SSH_FXP_READLINK
915 #define SFTP_SYMLINK SSH_FXP_SYMLINK
916 
917 /* openssh flags */
918 #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */
919 #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */
920 
921 #ifdef __cplusplus
922 } ;
923 #endif
924 
925 #endif /* SFTP_H */
926 
928 /* vim: set ts=2 sw=2 et cindent: */