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