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