1 /* 2 * psftp.h: interface between psftp.c / pscp.c, psftpcommon.c, and 3 * each platform-specific SFTP module. 4 */ 5 6 #ifndef PUTTY_PSFTP_H 7 #define PUTTY_PSFTP_H 8 9 /* 10 * psftp_getcwd returns the local current directory. The returned 11 * string must be freed by the caller. 12 */ 13 char *psftp_getcwd(void); 14 15 /* 16 * psftp_lcd changes the local current directory. The return value 17 * is NULL on success, or else an error message which must be freed 18 * by the caller. 19 */ 20 char *psftp_lcd(char *newdir); 21 22 /* 23 * Retrieve file times on a local file. Must return two unsigned 24 * longs in POSIX time_t format. 25 */ 26 void get_file_times(char *filename, unsigned long *mtime, 27 unsigned long *atime); 28 29 /* 30 * One iteration of the PSFTP event loop: wait for network data and 31 * process it, once. 32 */ 33 int ssh_sftp_loop_iteration(void); 34 35 /* 36 * Read a command line for PSFTP from standard input. Caller must 37 * free. 38 * 39 * If `backend_required' is true, should also listen for activity 40 * at the backend (rekeys, clientalives, unexpected closures etc) 41 * and respond as necessary, and if the backend closes it should 42 * treat this as a failure condition. If `backend_required' is 43 * false, a back end is not (intentionally) active at all (e.g. 44 * psftp before an `open' command). 45 */ 46 char *ssh_sftp_get_cmdline(const char *prompt, bool backend_required); 47 48 /* 49 * Platform-specific function called when we're about to make a 50 * network connection. 51 */ 52 void platform_psftp_pre_conn_setup(LogPolicy *lp); 53 54 /* 55 * The main program in psftp.c. Called from main() in the platform- 56 * specific code, after doing any platform-specific initialisation. 57 */ 58 int psftp_main(int argc, char *argv[]); 59 60 /* 61 * These functions are used by PSCP to transmit progress updates 62 * and error information to a GUI window managing it. This will 63 * probably only ever be supported on Windows, so these functions 64 * can safely be stubs on all other platforms. 65 */ 66 void gui_update_stats(const char *name, unsigned long size, 67 int percentage, unsigned long elapsed, 68 unsigned long done, unsigned long eta, 69 unsigned long ratebs); 70 void gui_send_errcount(int list, int errs); 71 void gui_send_char(int is_stderr, int c); 72 void gui_enable(const char *arg); 73 74 /* 75 * It's likely that a given platform's implementation of file 76 * transfer utilities is going to want to do things with them that 77 * aren't present in stdio. Hence we supply an alternative 78 * abstraction for file access functions. 79 * 80 * This abstraction tells you the size and access times when you 81 * open an existing file (platforms may choose the meaning of the 82 * file times if it's not clear; whatever they choose will be what 83 * PSCP sends to the server as mtime and atime), and lets you set 84 * the times when saving a new file. 85 * 86 * On the other hand, the abstraction is pretty simple: it supports 87 * only opening a file and reading it, or creating a file and writing 88 * it. None of this read-and-write, seeking-back-and-forth stuff. 89 */ 90 typedef struct RFile RFile; 91 typedef struct WFile WFile; 92 /* Output params size, perms, mtime and atime can all be NULL if 93 * desired. perms will be -1 if the OS does not support POSIX permissions. */ 94 RFile *open_existing_file(const char *name, uint64_t *size, 95 unsigned long *mtime, unsigned long *atime, 96 long *perms); 97 WFile *open_existing_wfile(const char *name, uint64_t *size); 98 /* Returns <0 on error, 0 on eof, or number of bytes read, as usual */ 99 int read_from_file(RFile *f, void *buffer, int length); 100 /* Closes and frees the RFile */ 101 void close_rfile(RFile *f); 102 WFile *open_new_file(const char *name, long perms); 103 /* Returns <0 on error, 0 on eof, or number of bytes written, as usual */ 104 int write_to_file(WFile *f, void *buffer, int length); 105 void set_file_times(WFile *f, unsigned long mtime, unsigned long atime); 106 /* Closes and frees the WFile */ 107 void close_wfile(WFile *f); 108 /* Seek offset bytes through file */ 109 enum { FROM_START, FROM_CURRENT, FROM_END }; 110 int seek_file(WFile *f, uint64_t offset, int whence); 111 /* Get file position */ 112 uint64_t get_file_posn(WFile *f); 113 /* 114 * Determine the type of a file: nonexistent, file, directory or 115 * weird. `weird' covers anything else - named pipes, Unix sockets, 116 * device files, fish, badgers, you name it. Things marked `weird' 117 * will be skipped over in recursive file transfers, so the only 118 * real reason for not lumping them in with `nonexistent' is that 119 * it allows a slightly more sane error message. 120 */ 121 enum { 122 FILE_TYPE_NONEXISTENT, FILE_TYPE_FILE, FILE_TYPE_DIRECTORY, FILE_TYPE_WEIRD 123 }; 124 int file_type(const char *name); 125 126 /* 127 * Read all the file names out of a directory. 128 */ 129 typedef struct DirHandle DirHandle; 130 DirHandle *open_directory(const char *name, const char **errmsg); 131 /* The string returned from this will need freeing if not NULL */ 132 char *read_filename(DirHandle *dir); 133 void close_directory(DirHandle *dir); 134 135 /* 136 * Test a filespec to see whether it's a local wildcard or not. 137 * Return values: 138 * 139 * - WCTYPE_WILDCARD (this is a wildcard). 140 * - WCTYPE_FILENAME (this is a single file name). 141 * - WCTYPE_NONEXISTENT (whichever it was, nothing of that name exists). 142 * 143 * Some platforms may choose not to support local wildcards when 144 * they come from the command line; in this case they simply never 145 * return WCTYPE_WILDCARD, but still test the file's existence. 146 * (However, all platforms will probably want to support wildcards 147 * inside the PSFTP CLI.) 148 */ 149 enum { 150 WCTYPE_NONEXISTENT, WCTYPE_FILENAME, WCTYPE_WILDCARD 151 }; 152 int test_wildcard(const char *name, bool cmdline); 153 154 /* 155 * Actually return matching file names for a local wildcard. 156 */ 157 typedef struct WildcardMatcher WildcardMatcher; 158 WildcardMatcher *begin_wildcard_matching(const char *name); 159 /* The string returned from this will need freeing if not NULL */ 160 char *wildcard_get_filename(WildcardMatcher *dir); 161 void finish_wildcard_matching(WildcardMatcher *dir); 162 163 /* 164 * Vet a filename returned from the remote host, to ensure it isn't 165 * in some way malicious. The idea is that this function is applied 166 * to filenames returned from FXP_READDIR, which means we can panic 167 * if we see _anything_ resembling a directory separator. 168 * 169 * Returns true if the filename is kosher, false if dangerous. 170 */ 171 bool vet_filename(const char *name); 172 173 /* 174 * Create a directory. Returns true on success, false on error. 175 */ 176 bool create_directory(const char *name); 177 178 /* 179 * Concatenate a directory name and a file name. The way this is 180 * done will depend on the OS. 181 */ 182 char *dir_file_cat(const char *dir, const char *file); 183 184 /* 185 * Return a pointer to the portion of str that comes after the last 186 * path component separator. 187 * 188 * If 'local' is false, path component separators are taken to just be 189 * '/', on the assumption that we're discussing the path syntax on the 190 * server. But if 'local' is true, the separators are whatever the 191 * local OS will treat that way - so that includes '\' and ':' on 192 * Windows. 193 * 194 * This function has the annoying strstr() property of taking a const 195 * char * and returning a char *. You should treat it as if it was a 196 * pair of overloaded functions, one mapping mutable->mutable and the 197 * other const->const :-( 198 */ 199 char *stripslashes(const char *str, bool local); 200 201 /* ---------------------------------------------------------------------- 202 * In psftpcommon.c 203 */ 204 205 /* 206 * qsort comparison routine for fxp_name structures. Sorts by real 207 * file name. 208 */ 209 int sftp_name_compare(const void *av, const void *bv); 210 211 /* 212 * Shared code for outputting a directory listing in response to a 213 * stream of name structures from FXP_READDIR operations. Used by 214 * psftp's ls command and pscp -ls. 215 */ 216 struct list_directory_from_sftp_ctx; 217 struct fxp_name; /* in sftp.h */ 218 struct list_directory_from_sftp_ctx *list_directory_from_sftp_new(void); 219 void list_directory_from_sftp_feed(struct list_directory_from_sftp_ctx *ctx, 220 struct fxp_name *name); 221 void list_directory_from_sftp_finish(struct list_directory_from_sftp_ctx *ctx); 222 void list_directory_from_sftp_free(struct list_directory_from_sftp_ctx *ctx); 223 /* Callbacks provided by the tool front end */ 224 void list_directory_from_sftp_warn_unsorted(void); 225 void list_directory_from_sftp_print(struct fxp_name *name); 226 227 #endif /* PUTTY_PSFTP_H */ 228