1/* 2 * Copyright 2002-2013 Haiku Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Tyler Dauwalder 7 * Axel Dörfler, axeld@pinc-software.de 8 * John Scipione, jscipione@gmail.com 9 * Ingo Weinhold, bonefish@users.sf.net 10 * 11 * Corresponds to: 12 * headers/os/storage/Path.h hrev47402 13 * src/kits/storage/Path.cpp hrev47402 14 */ 15 16 17/*! 18 \file Path.h 19 \ingroup storage 20 \ingroup libbe 21 \brief Provides the BPath class. 22*/ 23 24 25/*! 26 \class BPath 27 \ingroup storage 28 \ingroup libbe 29 \brief A class representing a file system path. 30 31 \since BeOS R3 32*/ 33 34 35/*! 36 \fn BPath::BPath() 37 \brief Creates an uninitialized BPath object. 38 39 \see SetTo() 40*/ 41 42 43/*! 44 \fn BPath::BPath(const BPath& path) 45 \brief Creates a copy of the given BPath object. 46 47 \param path the object to be copied. 48 49 \since BeOS R3 50*/ 51 52 53/*! 54 \fn BPath::BPath(const entry_ref* ref) 55 \brief Creates a BPath object and initializes it to the filesystem entry 56 specified by the passed in entry_ref struct. 57 58 \param ref the entry_ref to initialize from. 59 60 \since BeOS R5 61*/ 62 63 64/*! 65 \fn BPath::BPath(const BEntry* entry) 66 \brief Creates a BPath object and initializes it to the filesystem entry 67 specified by the passed in BEntry object. 68 69 \param entry the BEntry object to initialize from. 70 71 \since BeOS R4 72*/ 73 74 75/*! 76 \fn BPath::BPath(const char* dir, const char* leaf, bool normalize) 77 \brief Creates a BPath object and initializes it to the specified path or 78 path and filename combination. 79 80 \param dir The base component of the pathname. May be absolute or relative. 81 If relative, it is based off the current working directory. 82 \param leaf The (optional) leaf component of the pathname. Must be 83 relative. The value of \a leaf is concatenated to the end of \a dir 84 (a "/" will be added as a separator, if necessary). 85 \param normalize boolean flag used to force normalization; normalization 86 may sometimes occur even if \c false. The following items require 87 normalization: 88 - Relative pathnames (after concatenation; e.g. "boot/ltj") 89 - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar") 90 - Redundant slashes ("/boot//ltj") 91 - A trailing slash ("/boot/ltj/") 92 93 \since BeOS R3 94*/ 95 96 97/*! 98 \fn BPath::BPath(const BDirectory* dir, const char* leaf, bool normalize) 99 \brief Creates a BPath object and initializes it to the specified directory 100 and filename combination. 101 102 \param dir The directory that provides the base component of the pathname. 103 \param leaf The (optional) leaf component of the pathname. Must be 104 relative. The value of \a leaf is concatenated to the end of \a dir 105 (a "/" will be added as a separator, if necessary). 106 \param normalize boolean flag used to force normalization; normalization 107 may sometimes occur even if \c false. The following items require 108 normalization: 109 - Relative pathnames (after concatenation; e.g. "boot/ltj") 110 - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar") 111 - Redundant slashes ("/boot//ltj") 112 - A trailing slash ("/boot/ltj/") 113 114 \since BeOS R3 115*/ 116 117 118/*! 119 \fn BPath::~BPath() 120 \brief Destroys the BPath object and frees any associated resources. 121 122 \since BeOS R3 123*/ 124 125 126/*! 127 \name Constructor Helpers 128*/ 129 130 131//! @{ 132 133 134/*! 135 \fn status_t BPath::InitCheck() const 136 \brief Checks whether or not the object was properly initialized. 137 138 \return \c B_OK, if the BPath object was properly initialized, an error 139 code otherwise. 140 141 \since BeOS R3 142*/ 143 144 145/*! 146 \fn status_t BPath::SetTo(const entry_ref* ref) 147 \brief Reinitializes the object to the filesystem entry specified by the 148 passed in entry_ref struct. 149 \param ref The entry_ref to reinitialize the entry from. 150 151 \returns A status code. 152 \retval B_OK Initialization was successful. 153 \retval B_BAD_VALUE \a ref was \c NULL. 154 \retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH. 155 156 \since BeOS R5 157*/ 158 159 160/*! 161 \fn status_t BPath::SetTo(const BEntry* entry) 162 \brief Reinitializes the object to the specified filesystem entry. 163 164 \param entry The BEntry to reinitialize the entry from. 165 166 \returns A status code. 167 \retval B_OK Initialization was successful. 168 \retval B_BAD_VALUE \a ref was \c NULL. 169 \retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH. 170 171 \since BeOS R4 172*/ 173 174 175/*! 176 \fn status_t BPath::SetTo(const char* path, const char* leaf, bool normalize) 177 \brief Reinitializes the object to the passed in \a path or \a path and 178 \a leaf combination. 179 180 \remarks The following pseudocode is safe: 181 \code path.SetTo(path.Path(), "new leaf") \endcode 182 183 \param path The \a path name to use. 184 \param leaf The \a leaf name to use (may be \c NULL). 185 \param normalize Boolean flag used to force normalization; normalization 186 may sometimes occur even if \c false. The following items require 187 normalization: 188 - Relative pathnames (after concatenation; e.g. "boot/ltj") 189 - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar") 190 - Redundant slashes ("/boot//ltj") 191 - A trailing slash ("/boot/ltj/") 192 193 \returns A status code. 194 \retval B_OK Initialization was successful. 195 \retval B_BAD_VALUE \a ref was \c NULL. 196 \retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH. 197 198 \since BeOS R3 199*/ 200 201 202/*! 203 \fn status_t BPath::SetTo(const BDirectory* dir, const char* path, 204 bool normalize) 205 \brief Reinitializes the object to the passed in \a dir and relative 206 \a path combination. 207 208 \param dir The directory that provides the base component of the pathname. 209 \param path the relative \a path name (may be \c NULL). 210 \param normalize boolean flag used to force normalization; normalization 211 may sometimes occur even if \c false. The following items require 212 normalization: 213 - Relative pathnames (after concatenation; e.g. "boot/ltj") 214 - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar") 215 - Redundant slashes ("/boot//ltj") 216 - A trailing slash ("/boot/ltj/") 217 218 \returns A status code. 219 \retval B_OK Initialization was successful. 220 \retval B_BAD_VALUE \a ref was \c NULL. 221 \retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH. 222 223 \since BeOS R3 224*/ 225 226 227/*! 228 \fn void BPath::Unset() 229 \brief Returns the object to an uninitialized state. 230 231 Frees any resources it allocated and marks the object as uninitialized. 232 233 \since BeOS R3 234*/ 235 236 237//! @} 238 239 240/*! 241 \name Path Manipulation 242*/ 243 244 245//! @{ 246 247 248/*! 249 \fn status_t BPath::Append(const char* path, bool normalize) 250 \brief Appends the passed in relative path to the end of the current path. 251 252 This method fails if the path is absolute or the BPath object is 253 uninitialized. 254 255 \param path Relative pathname to append to current path (may be \c NULL). 256 \param normalize Boolean flag used to force normalization; normalization 257 may sometimes occur even if \c false. The following items require 258 normalization: 259 - Relative pathnames (after concatenation; e.g. "boot/ltj") 260 - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar") 261 - Redundant slashes ("/boot//ltj") 262 - A trailing slash ("/boot/ltj/") 263 264 \returns A status code. 265 \retval B_OK Initialization was successful. 266 \retval B_BAD_VALUE \a ref was \c NULL. 267 \retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH. 268 269 \since BeOS R3 270*/ 271 272 273//! @} 274 275 276/*! 277 \name Path Information 278*/ 279 280 281//! @{ 282 283 284/*! 285 \fn const char* BPath::Path() const 286 \brief Gets the entire path of the object. 287 288 \returns The path name of the object, or \c NULL if it is not properly 289 initialized. 290 291 \since BeOS R3 292*/ 293 294 295/*! 296 \fn const char* BPath::Leaf() const 297 \brief Gets the leaf portion of the path. 298 299 The leaf portion of the path is defined to be the string after the last 300 \c '/'. For the root path (\c "/") it is an empty string (\c ""). 301 302 \returns The leaf portion of the path or \c NULL if it is not properly 303 initialized. 304 305 \since BeOS R3 306*/ 307 308 309/*! 310 \fn status_t BPath::GetParent(BPath* path) const 311 \brief Initializes \a path with the parent directory of the BPath object. 312 313 No normalization is performed on the path. 314 315 \param path The BPath object to be initialized to the parent directory. 316 317 \returns A status code. 318 \retval B_OK Everything went fine. 319 \retval B_BAD_VALUE \a path was \c NULL. 320 \retval B_ENTRY_NOT_FOUND The BPath object represents the root path and 321 thus has no parent. 322*/ 323 324 325/*! 326 \fn bool BPath::IsAbsolute() const 327 \brief Gets whether or not the path is absolute or relative. 328 329 \warning This method returns \c false if the object is initialized. 330 331 \returns \c true if the path is absolute, \c false if relative or if the 332 object is uninitialized. 333*/ 334 335 336//! @} 337 338 339/*! 340 \name Operators 341*/ 342 343 344//! @{ 345 346 347/*! 348 \fn bool BPath::operator==(const BPath& item) const 349 \brief Performs a simple (string-wise) comparison of paths for equality. 350 351 \warning No normalization takes place, two uninitialized BPath objects are 352 considered equal. 353 354 \param item the BPath object to compare. 355 356 \return \c true, if the paths are equal, \c false otherwise. 357 358 \since BeOS R3 359*/ 360 361 362/*! 363 \fn bool BPath::operator==(const char* path) const 364 \brief Performs a simple (string-wise) comparison of paths for equality. 365 366 \warning No normalization takes place. 367 368 \param path The path to compare. 369 370 \return \c true, if the path names are equal, \c false otherwise. 371 372 \since BeOS R3 373*/ 374 375 376/*! 377 \fn bool BPath::operator!=(const BPath& item) const 378 \brief Performs a simple (string-wise) comparison of paths for inequality. 379 380 \warning No normalization takes place, two uninitialized BPath objects are 381 considered equal. 382 383 \param item the BPath object to compare. 384 385 \return \c true, if the path names are \b not equal, \c false otherwise. 386 387 \since BeOS R3 388*/ 389 390 391/*! 392 \fn bool BPath::operator!=(const char* path) const 393 \brief Performs a simple (string-wise) comparison of paths for inequality. 394 395 \warning No normalization takes place. 396 397 \param path The path to compare. 398 399 \return \c true, if the path names are \b not equal, \c false otherwise. 400 401 \since BeOS R3 402*/ 403 404 405/*! 406 \fn BPath& BPath::operator=(const BPath& item) 407 \brief Initializes the object as a copy of \a item. 408 409 \param item The BPath object to copy 410 411 \return A pointer to the newly initialized BPath object. 412 413 \since BeOS R3 414*/ 415 416 417/*! 418 \fn BPath& BPath::operator=(const char* path) 419 \brief Initializes the object with the passed in \a path. 420 421 Has the same effect as \code SetTo(path) \endcode 422 423 \param path the path to be assign to this object. 424 425 \return A pointer to the newly initialized BPath object. 426 427 \since BeOS R3 428*/ 429 430 431//! @} 432 433 434/*! 435 \name BFlattenable Method Implementations 436*/ 437 438 439//! @{ 440 441 442/*! 443 \fn bool BPath::IsFixedSize() const 444 \brief Implements BFlattenable::IsFixedSize(). Always returns \c false. 445 446 \return \c false 447 448 \since BeOS R3 449*/ 450 451 452/*! 453 \fn type_code BPath::TypeCode() const 454 \brief Implements BFlattenable::TypeCode(). Always returns \c B_REF_TYPE. 455 456 \return \c B_REF_TYPE 457 458 \since BeOS R3 459*/ 460 461 462/*! 463 \fn ssize_t BPath::FlattenedSize() const 464 \brief Implements BFlattenable::FlattenedSize(). Gets the size of the 465 flattened entry_ref struct that represents the path in bytes. 466 467 \return The size of the flattened entry_ref struct that represents the 468 path in bytes. 469 470 \since BeOS R3 471*/ 472 473 474/*! 475 \fn status_t BPath::Flatten(void* buffer, ssize_t size) const 476 \brief Implements BFlattenable::Flatten(). Converts the path of the object 477 to an entry_ref and writes it into <em>buffer</em>. 478 479 \param buffer The buffer that the data is to be stored in. 480 \param size Size of <em>buffer</em>. 481 482 \returns A status code. 483 \retval B_OK Everything went fine. 484 \retval B_BAD_VALUE \a buffer was \c NULL or of insufficient size. 485 486 \since BeOS R3 487*/ 488 489 490/*! 491 \fn bool BPath::AllowsTypeCode(type_code code) const 492 \brief Implements BFlattenable::AllowsTypeCode(). Checks if type code is 493 equal to \c B_REF_TYPE. 494 495 \param code The type code to test. 496 497 \return \c true if code is \c B_REF_TYPE, \c false otherwise. 498 499 \since BeOS R3 500*/ 501 502 503/*! 504 \fn status_t BPath::Unflatten(type_code code, const void* buffer, 505 ssize_t size) 506 \brief Implements BFlattenable::Unflatten(). Initializes the object with 507 the flattened entry_ref data from the passed in buffer. 508 509 The type code must be set to \c B_REF_TYPE. 510 511 \param code The type code of the flattened data, must be \c B_REF_TYPE. 512 \param buffer A pointer to a buffer containing the flattened data. 513 \param size The size of \a buffer in bytes. 514 515 \returns A status code. 516 \retval B_OK Everything went fine. 517 \retval B_BAD_VALUE \a buffer was \c NULL or didn't contain an entry_ref. 518 519 \since BeOS R3 520*/ 521 522 523//! @} 524