1 /* 2 * Copyright (c) 2006-2011 Christian Plattner. All rights reserved. 3 * Please refer to the LICENSE.txt for licensing details. 4 */ 5 package ch.ethz.ssh2.sftp; 6 7 /** 8 * 9 * SFTP Open Flags. 10 * 11 * The following table is provided to assist in mapping POSIX semantics 12 * to equivalent SFTP file open parameters: 13 * <p> 14 * TODO: This comment should be moved to the open method. 15 * <p> 16 * <ul> 17 * <li>O_RDONLY 18 * <ul><li>desired-access = READ_DATA | READ_ATTRIBUTES</li></ul> 19 * </li> 20 * </ul> 21 * <ul> 22 * <li>O_WRONLY 23 * <ul><li>desired-access = WRITE_DATA | WRITE_ATTRIBUTES</li></ul> 24 * </li> 25 * </ul> 26 * <ul> 27 * <li>O_RDWR 28 * <ul><li>desired-access = READ_DATA | READ_ATTRIBUTES | WRITE_DATA | WRITE_ATTRIBUTES</li></ul> 29 * </li> 30 * </ul> 31 * <ul> 32 * <li>O_APPEND 33 * <ul> 34 * <li>desired-access = WRITE_DATA | WRITE_ATTRIBUTES | APPEND_DATA</li> 35 * <li>flags = SSH_FXF_ACCESS_APPEND_DATA and or SSH_FXF_ACCESS_APPEND_DATA_ATOMIC</li> 36 * </ul> 37 * </li> 38 * </ul> 39 * <ul> 40 * <li>O_CREAT 41 * <ul> 42 * <li>flags = SSH_FXF_OPEN_OR_CREATE</li> 43 * </ul> 44 * </li> 45 * </ul> 46 * <ul> 47 * <li>O_TRUNC 48 * <ul> 49 * <li>flags = SSH_FXF_TRUNCATE_EXISTING</li> 50 * </ul> 51 * </li> 52 * </ul> 53 * <ul> 54 * <li>O_TRUNC|O_CREATE 55 * <ul> 56 * <li>flags = SSH_FXF_CREATE_TRUNCATE</li> 57 * </ul> 58 * </li> 59 * </ul> 60 * 61 * @author Christian Plattner 62 * @version 2.50, 03/15/10 63 */ 64 public class OpenFlags 65 { 66 /** 67 * Disposition is a 3 bit field that controls how the file is opened. 68 * The server MUST support these bits (possible enumaration values: 69 * SSH_FXF_CREATE_NEW, SSH_FXF_CREATE_TRUNCATE, SSH_FXF_OPEN_EXISTING, 70 * SSH_FXF_OPEN_OR_CREATE or SSH_FXF_TRUNCATE_EXISTING). 71 */ 72 public static final int SSH_FXF_ACCESS_DISPOSITION = 0x00000007; 73 74 /** 75 * A new file is created; if the file already exists, the server 76 * MUST return status SSH_FX_FILE_ALREADY_EXISTS. 77 */ 78 public static final int SSH_FXF_CREATE_NEW = 0x00000000; 79 80 /** 81 * A new file is created; if the file already exists, it is opened 82 * and truncated. 83 */ 84 public static final int SSH_FXF_CREATE_TRUNCATE = 0x00000001; 85 86 /** 87 * An existing file is opened. If the file does not exist, the 88 * server MUST return SSH_FX_NO_SUCH_FILE. If a directory in the 89 * path does not exist, the server SHOULD return 90 * SSH_FX_NO_SUCH_PATH. It is also acceptable if the server 91 * returns SSH_FX_NO_SUCH_FILE in this case. 92 */ 93 public static final int SSH_FXF_OPEN_EXISTING = 0x00000002; 94 95 /** 96 * If the file exists, it is opened. If the file does not exist, 97 * it is created. 98 */ 99 public static final int SSH_FXF_OPEN_OR_CREATE = 0x00000003; 100 101 /** 102 * An existing file is opened and truncated. If the file does not 103 * exist, the server MUST return the same error codes as defined 104 * for SSH_FXF_OPEN_EXISTING. 105 */ 106 public static final int SSH_FXF_TRUNCATE_EXISTING = 0x00000004; 107 108 /** 109 * Data is always written at the end of the file. The offset field 110 * of the SSH_FXP_WRITE requests are ignored. 111 * <p> 112 * Data is not required to be appended atomically. This means that 113 * if multiple writers attempt to append data simultaneously, data 114 * from the first may be lost. However, data MAY be appended 115 * atomically. 116 */ 117 public static final int SSH_FXF_ACCESS_APPEND_DATA = 0x00000008; 118 119 /** 120 * Data is always written at the end of the file. The offset field 121 * of the SSH_FXP_WRITE requests are ignored. 122 * <p> 123 * Data MUST be written atomically so that there is no chance that 124 * multiple appenders can collide and result in data being lost. 125 * <p> 126 * If both append flags are specified, the server SHOULD use atomic 127 * append if it is available, but SHOULD use non-atomic appends 128 * otherwise. The server SHOULD NOT fail the request in this case. 129 */ 130 public static final int SSH_FXF_ACCESS_APPEND_DATA_ATOMIC = 0x00000010; 131 132 /** 133 * Indicates that the server should treat the file as text and 134 * convert it to the canonical newline convention in use. 135 * (See Determining Server Newline Convention in section 5.3 in the 136 * SFTP standard draft). 137 * <p> 138 * When a file is opened with this flag, the offset field in the read 139 * and write functions is ignored. 140 * <p> 141 * Servers MUST process multiple, parallel reads and writes correctly 142 * in this mode. Naturally, it is permissible for them to do this by 143 * serializing the requests. 144 * <p> 145 * Clients SHOULD use the SSH_FXF_ACCESS_APPEND_DATA flag to append 146 * data to a text file rather then using write with a calculated offset. 147 */ 148 public static final int SSH_FXF_ACCESS_TEXT_MODE = 0x00000020; 149 150 /** 151 * The server MUST guarantee that no other handle has been opened 152 * with ACE4_READ_DATA access, and that no other handle will be 153 * opened with ACE4_READ_DATA access until the client closes the 154 * handle. (This MUST apply both to other clients and to other 155 * processes on the server.) 156 * <p> 157 * If there is a conflicting lock the server MUST return 158 * SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 159 * guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 160 * <p> 161 * Other handles MAY be opened for ACE4_WRITE_DATA or any other 162 * combination of accesses, as long as ACE4_READ_DATA is not included 163 * in the mask. 164 */ 165 public static final int SSH_FXF_ACCESS_BLOCK_READ = 0x00000040; 166 167 /** 168 * The server MUST guarantee that no other handle has been opened 169 * with ACE4_WRITE_DATA or ACE4_APPEND_DATA access, and that no other 170 * handle will be opened with ACE4_WRITE_DATA or ACE4_APPEND_DATA 171 * access until the client closes the handle. (This MUST apply both 172 * to other clients and to other processes on the server.) 173 * <p> 174 * If there is a conflicting lock the server MUST return 175 * SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 176 * guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 177 * <p> 178 * Other handles MAY be opened for ACE4_READ_DATA or any other 179 * combination of accesses, as long as neither ACE4_WRITE_DATA nor 180 * ACE4_APPEND_DATA are included in the mask. 181 */ 182 public static final int SSH_FXF_ACCESS_BLOCK_WRITE = 0x00000080; 183 184 /** 185 * The server MUST guarantee that no other handle has been opened 186 * with ACE4_DELETE access, opened with the 187 * SSH_FXF_ACCESS_DELETE_ON_CLOSE flag set, and that no other handle 188 * will be opened with ACE4_DELETE access or with the 189 * SSH_FXF_ACCESS_DELETE_ON_CLOSE flag set, and that the file itself 190 * is not deleted in any other way until the client closes the handle. 191 * <p> 192 * If there is a conflicting lock the server MUST return 193 * SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 194 * guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 195 */ 196 public static final int SSH_FXF_ACCESS_BLOCK_DELETE = 0x00000100; 197 198 /** 199 * If this bit is set, the above BLOCK modes are advisory. In advisory 200 * mode, only other accesses that specify a BLOCK mode need be 201 * considered when determining whether the BLOCK can be granted, 202 * and the server need not prevent I/O operations that violate the 203 * block mode. 204 * <p> 205 * The server MAY perform mandatory locking even if the BLOCK_ADVISORY 206 * bit is set. 207 */ 208 public static final int SSH_FXF_ACCESS_BLOCK_ADVISORY = 0x00000200; 209 210 /** 211 * If the final component of the path is a symlink, then the open 212 * MUST fail, and the error SSH_FX_LINK_LOOP MUST be returned. 213 */ 214 public static final int SSH_FXF_ACCESS_NOFOLLOW = 0x00000400; 215 216 /** 217 * The file should be deleted when the last handle to it is closed. 218 * (The last handle may not be an sftp-handle.) This MAY be emulated 219 * by a server if the OS doesn't support it by deleting the file when 220 * this handle is closed. 221 * <p> 222 * It is implementation specific whether the directory entry is 223 * removed immediately or when the handle is closed. 224 */ 225 public static final int SSH_FXF_ACCESS_DELETE_ON_CLOSE = 0x00000800; 226 } 227