1/* 2 * Copyright 2009-2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Tyler Dauwalder 7 * John Scipione, jscipione@gmail.com 8 * Ingo Weinhold, bonefish@users.sf.net 9 * 10 * Corresponds to: 11 * headers/os/storage/File.h hrev47402 12 * src/kits/storage/File.cpp hrev47402 13 */ 14 15 16/*! 17 \file File.h 18 \ingroup storage 19 \ingroup libbe 20 \brief Provides the BFile class. 21*/ 22 23 24/*! 25 \class BFile 26 \ingroup storage 27 \ingroup libbe 28 \brief Provides the ability to read and write the data of a file. 29 30 The file is automatically opened when you initialize a BFile and is 31 automatically closed when you re-initialize or destroy the object. 32 33 Symbolic links are automatically transversed by opening a BFile. 34 The node that the BFile ends up opening will be the file or directory 35 that the link points to, not the symbolic link file itself. 36 37 \since BeOS R3 38*/ 39 40 41/*! 42 \fn BFile::BFile() 43 \brief Creates an uninitialized BFile object. 44 45 Should be followed by a call to one of the SetTo() methods, or an 46 assignment: 47 - SetTo(const entry_ref* ref, uint32 openMode) 48 - SetTo(const BEntry* entry, uint32 openMode) 49 - SetTo(const char* path, uint32 openMode) 50 - SetTo(const BDirectory* dir, const char* path, uint32 openMode) 51 - operator=(const BFile &file) 52 53 \since BeOS R3 54*/ 55 56 57/*! 58 \fn BFile::BFile(const BFile& file) 59 \brief Creates a copy of the supplied BFile. 60 61 If \a file is uninitialized, the newly constructed BFile will be too. 62 63 \param file The BFile object to be copied. 64 65 \since BeOS R3 66*/ 67 68 69/*! 70 \fn BFile::BFile(const entry_ref* ref, uint32 openMode) 71 \brief Creates a BFile and initializes it to the file referred to by 72 the supplied entry_ref and according to the specified open mode. 73 74 \param ref The entry_ref referring to the file. 75 \param openMode The mode in which the file should be opened. 76 77 \see SetTo(const entry_ref* ref, uint32 openMode) 78 79 \since BeOS R3 80*/ 81 82 83/*! 84 \fn BFile::BFile(const BEntry* entry, uint32 openMode) 85 \brief Creates a BFile and initializes it to the file referred to by 86 the supplied BEntry and according to the specified open mode. 87 88 \param entry The BEntry referring to the file. 89 \param openMode The mode in which the file should be opened. 90 91 \see SetTo(const BEntry* entry, uint32 openMode) 92 93 \since BeOS R3 94*/ 95 96 97/*! 98 \fn BFile::BFile(const char* path, uint32 openMode) 99 \brief Creates a BFile and initializes it to the file referred to by 100 the supplied path name and according to the specified open mode. 101 102 \param path The file's path name. 103 \param openMode The mode in which the file should be opened. 104 105 \see SetTo(const char* path, uint32 openMode) 106 107 \since BeOS R3 108*/ 109 110 111/*! 112 \fn BFile::BFile(const BDirectory *dir, const char* path, uint32 openMode) 113 \brief Creates a BFile and initializes it to the file referred to by 114 the supplied path name relative to the specified BDirectory and 115 according to the specified open mode. 116 117 \param dir The BDirectory, relative to which the file's path name is 118 given. 119 \param path The file's path name relative to \a dir. 120 \param openMode The mode in which the file should be opened. 121 122 \see SetTo(const BDirectory* dir, const char* path, uint32 openMode) 123 124 \since BeOS R3 125*/ 126 127 128/*! 129 \fn BFile::~BFile() 130 \brief Destroys the BFile object and frees all allocated resources. 131 132 If the file is properly initialized, the file descriptor is closed. 133 134 \since BeOS R3 135*/ 136 137 138/*! 139 \fn status_t BFile::SetTo(const entry_ref* ref, uint32 openMode) 140 \brief Re-initializes the BFile to the file referred to by the 141 supplied entry_ref and according to the specified open mode. 142 143 \param ref The entry_ref referring to the file. 144 \param openMode The mode in which the file should be opened 145 \a openMode must be a bitwise or of exactly one of the flags. 146 - \c B_READ_ONLY: The file is opened read only. 147 - \c B_WRITE_ONLY: The file is opened write only. 148 - \c B_READ_WRITE: The file is opened for random read/write access. 149 and any number of the flags 150 - \c B_CREATE_FILE: A new file will be created, if it does not 151 already exist. 152 - \c B_FAIL_IF_EXISTS: If the file does already exist and 153 \c B_CREATE_FILE is set, SetTo() fails. 154 - \c B_ERASE_FILE: An already existing file is truncated to zero 155 size. 156 - \c B_OPEN_AT_END: Seek() to the end of the file after opening. 157 158 \returns A status code. 159 \retval B_OK Everything went fine. 160 \retval B_BAD_VALUE \c NULL \a ref or bad \a openMode. 161 \retval B_ENTRY_NOT_FOUND File not found or failed to create file. 162 \retval B_FILE_EXISTS File exists and \c B_FAIL_IF_EXISTS was passed. 163 \retval B_PERMISSION_DENIED File permissions didn't allow operation. 164 \retval B_NO_MEMORY Insufficient memory for operation. 165 \retval B_LINK_LIMIT Indicates a cyclic loop within the file system. 166 \retval B_BUSY A node was busy. 167 \retval B_FILE_ERROR A general file error. 168 \retval B_NO_MORE_FDS The application has run out of file descriptors. 169 170 \since BeOS R3 171*/ 172 173 174/*! 175 \fn status_t BFile::SetTo(const BEntry* entry, uint32 openMode) 176 \brief Re-initializes the BFile to the file referred to by the 177 supplied BEntry and according to the specified open mode. 178 179 \param entry the BEntry referring to the file 180 \param openMode the mode in which the file should be opened 181 182 \returns A status code. 183 \retval B_OK Everything went fine. 184 \retval B_BAD_VALUE \c NULL \a entry or bad \a openMode. 185 \retval B_ENTRY_NOT_FOUND File not found or failed to create file. 186 \retval B_FILE_EXISTS File exists and \c B_FAIL_IF_EXISTS was passed. 187 \retval B_PERMISSION_DENIED File permissions didn't allow operation. 188 \retval B_NO_MEMORY Insufficient memory for operation. 189 \retval B_LINK_LIMIT Indicates a cyclic loop within the file system. 190 \retval B_BUSY A node was busy. 191 \retval B_FILE_ERROR A general file error. 192 \retval B_NO_MORE_FDS The application has run out of file descriptors. 193 194 \todo Implemented using SetTo(entry_ref*, uint32). Check, if necessary 195 to re-implement! 196 197 \since BeOS R3 198*/ 199 200 201/*! 202 \fn status_t BFile::SetTo(const char* path, uint32 openMode) 203 \brief Re-initializes the BFile to the file referred to by the 204 supplied path name and according to the specified open mode. 205 206 \param path The file's path name. 207 \param openMode The mode in which the file should be opened. 208 209 \returns A status code. 210 \retval B_OK Everything went fine. 211 \retval B_BAD_VALUE \c NULL \a path or bad \a openMode. 212 \retval B_ENTRY_NOT_FOUND File not found or failed to create file. 213 \retval B_FILE_EXISTS File exists and \c B_FAIL_IF_EXISTS was passed. 214 \retval B_PERMISSION_DENIED File permissions didn't allow operation. 215 \retval B_NO_MEMORY Insufficient memory for operation. 216 \retval B_LINK_LIMIT Indicates a cyclic loop within the file system. 217 \retval B_BUSY A node was busy. 218 \retval B_FILE_ERROR A general file error. 219 \retval B_NO_MORE_FDS The application has run out of file descriptors. 220 221 \since BeOS R3 222*/ 223 224 225/*! 226 \fn status_t BFile::SetTo(const BDirectory* dir, const char* path, 227 uint32 openMode) 228 \brief Re-initializes the BFile to the file referred to by the 229 supplied path name relative to the specified BDirectory and 230 according to the specified open mode. 231 232 \param dir The BDirectory, relative to which the file's path name is 233 given. 234 \param path The file's path name relative to \a dir. 235 \param openMode The mode in which the file should be opened. 236 237 \returns A status code. 238 \retval B_OK Everything went fine. 239 \retval B_BAD_VALUE \c NULL \a dir or \a path or bad \a openMode. 240 \retval B_ENTRY_NOT_FOUND File not found or failed to create file. 241 \retval B_FILE_EXISTS File exists and \c B_FAIL_IF_EXISTS was passed. 242 \retval B_PERMISSION_DENIED File permissions didn't allow operation. 243 \retval B_NO_MEMORY Insufficient memory for operation. 244 \retval B_LINK_LIMIT Indicates a cyclic loop within the file system. 245 \retval B_BUSY A node was busy. 246 \retval B_FILE_ERROR A general file error. 247 \retval B_NO_MORE_FDS The application has run out of file descriptors. 248 249 \todo Implemented using SetTo(BEntry*, uint32). Check, if necessary 250 to re-implement! 251 252 \since BeOS R3 253*/ 254 255 256/*! 257 \fn bool BFile::IsReadable() const 258 \brief Reports whether or not the file is readable. 259 260 \return 261 - \c true, if the BFile has been initialized properly and the file has 262 been been opened for reading, 263 - \c false, otherwise. 264 265 \since BeOS R3 266*/ 267 268 269/*! 270 \fn bool BFile::IsWritable() const 271 \brief Reports whether or not the file is writable. 272 273 \return 274 - \c true, if the BFile has been initialized properly and the file has 275 been opened for writing, 276 - \c false, otherwise. 277 278 \since BeOS R3 279*/ 280 281 282/*! 283 \fn ssize_t BFile::Read(void* buffer, size_t size) 284 \brief Reads a number of bytes from the file into a buffer. 285 286 \param buffer The buffer the data from the file shall be written to. 287 \param size The number of bytes that shall be read. 288 289 \returns The number of bytes read or an error code. 290 291 \since BeOS R3 292*/ 293 294 295/*! 296 \fn ssize_t BFile::ReadAt(off_t location, void* buffer, size_t size) 297 \brief Reads a number of bytes from a certain position within the file 298 into a buffer. 299 300 \param location The position (in bytes) within the file from which the 301 data shall be read. 302 \param buffer The buffer the data from the file shall be written to. 303 \param size The number of bytes that shall be read. 304 305 \returns The number of bytes read or an error code. 306 307 \since BeOS R3 308*/ 309 310 311/*! 312 \fn ssize_t BFile::Write(const void* buffer, size_t size) 313 \brief Writes a number of bytes from a buffer into the file. 314 315 \param buffer The buffer containing the data to be written to the file. 316 \param size The number of bytes that shall be written. 317 318 \returns The number of bytes actually written or an error code. 319 320 \since BeOS R3 321*/ 322 323 324/*! 325 \fn ssize_t BFile::WriteAt(off_t location, const void* buffer, size_t size) 326 \brief Writes a number of bytes from a buffer at a certain position 327 into the file. 328 329 \param location The position (in bytes) within the file at which the data 330 shall be written. 331 \param buffer The buffer containing the data to be written to the file. 332 \param size The number of bytes that shall be written. 333 334 \returns The number of bytes actually written or an error code. 335 336 \since BeOS R3 337*/ 338 339 340/*! 341 \fn off_t BFile::Seek(off_t offset, uint32 seekMode) 342 \brief Seeks to another read/write position within the file. 343 344 It is allowed to seek past the end of the file. A subsequent call to 345 Write() will pad the file with undefined data. Seeking before the 346 beginning of the file will fail and the behavior of subsequent Read() 347 or Write() invocations will be undefined. 348 349 \param offset New read/write position, depending on \a seekMode relative 350 to the beginning or the end of the file or the current position. 351 \param seekMode 352 - \c SEEK_SET: move relative to the beginning of the file. 353 - \c SEEK_CUR: move relative to the current position. 354 - \c SEEK_END: move relative to the end of the file. 355 356 \returns The new read/write position relative to the beginning of the 357 file or an error code. 358 \retval B_ERROR Trying to seek before the beginning of the file. 359 \retval B_FILE_ERROR The file is not properly initialized. 360 361 \since BeOS R3 362*/ 363 364 365/*! 366 \fn off_t BFile::Position() const 367 \brief Gets the current read/write position within the file. 368 369 \returns The current read/write position relative to the beginning of the 370 file or an error code. 371 \retval B_ERROR After a Seek() before the beginning of the file. 372 \retval B_FILE_ERROR The file has not been initialized. 373 374 \since BeOS R3 375*/ 376 377 378/*! 379 \fn status_t BFile::SetSize(off_t size) 380 \brief Sets the size of the file. 381 382 If the file is shorter than \a size bytes it will be padded with 383 unspecified data to the requested size. If it is larger, it will be 384 truncated. 385 386 \note There's no problem with setting the size of a BFile opened in 387 \c B_READ_ONLY mode, unless the file resides on a read only volume. 388 389 \param size The new file size. 390 391 \returns A status code. 392 \retval B_OK Everything went fine. 393 \retval B_NOT_ALLOWED Trying to set the size of a file on a read only 394 volume. 395 \retval B_DEVICE_FULL There's not enough space left on the volume. 396 397 \since BeOS R3 398*/ 399 400 401/*! 402 \fn status_t BFile::GetSize(off_t* size) const 403 \brief Gets the size of the file. 404 405 \param size The file size to fill out. 406 407 \returns A status code. 408 409 \see BStatable::GetSize() 410 411 \since BeOS R3 412*/ 413 414 415/*! 416 \fn BFile& BFile::operator=(const BFile &file) 417 \brief Assigns another BFile to this BFile. 418 419 If the other BFile is uninitialized, this one will be too. Otherwise it 420 will refer to the same file using the same mode, unless an error occurs. 421 422 \param file The original BFile to assign from. 423 424 \returns A reference to the assigned BFile. 425 426 \since BeOS R3 427*/ 428