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