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