[haiku-commits] haiku: hrev45309 - docs/user/storage src/kits/storage headers/os/storage
- From: jscipione@xxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Wed, 20 Feb 2013 22:21:06 +0100 (CET)
hrev45309 adds 1 changeset to branch 'master'
old head: 29f51b3431d903923f25fd15cf8afb3c90d1ddb3
new head: 434716ced8ad33189ce77ac2174dbee94e58e4fc
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=434716c+%5E29f51b3
----------------------------------------------------------------------------
434716c: Add BSymLink class docs to Haiku Book
[ John Scipione <jscipione@xxxxxxxxx> ]
----------------------------------------------------------------------------
Revision: hrev45309
Commit: 434716ced8ad33189ce77ac2174dbee94e58e4fc
URL: http://cgit.haiku-os.org/haiku/commit/?id=434716c
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Wed Feb 20 21:20:53 2013 UTC
----------------------------------------------------------------------------
3 files changed, 216 insertions(+), 113 deletions(-)
docs/user/storage/SymLink.dox | 159 ++++++++++++++++++++++++++++++++++++++
headers/os/storage/SymLink.h | 56 ++++++--------
src/kits/storage/SymLink.cpp | 114 ++++++++-------------------
----------------------------------------------------------------------------
diff --git a/docs/user/storage/SymLink.dox b/docs/user/storage/SymLink.dox
new file mode 100644
index 0000000..ca2ff05
--- /dev/null
+++ b/docs/user/storage/SymLink.dox
@@ -0,0 +1,159 @@
+/*
+ * Copyright 2002-2013 Haiku Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ * Tyler Dauwalder
+ * John Scipione, jscipione@xxxxxxxxx
+ * Ingo Weinhold, bonefish@xxxxxxxxxxxx
+ *
+ * Corresponds to:
+ * headers/os/storage/Symlink.h hrev45306
+ * src/kits/storage/Symlink.cpp hrev45306
+ */
+
+
+/*!
+ \file Symlink.h
+ \ingroup storage
+ \ingroup libbe
+ \brief Provides the BSymLink class.
+*/
+
+
+/*!
+ \class BSymLink
+ \ingroup storage
+ \ingroup libbe
+ \brief Provides an interface for creating, manipulating, and accessing
+ the contents of symbolic links.
+*/
+
+
+/*!
+ \fn BSymLink::BSymLink()
+ \brief Creates an uninitialized BSymLink object.
+*/
+
+
+/*!
+ \fn BSymLink::BSymLink(const BSymLink &link)
+ \brief Creates a copy of the supplied BSymLink object.
+
+ \param link The BSymLink object to be copied.
+*/
+
+
+/*!
+ \fn BSymLink::BSymLink(const entry_ref *ref)
+ \brief Creates a BSymLink object and initializes it to the symbolic link
+ referred to by the supplied entry_ref.
+
+ \param ref the entry_ref referring to the symbolic link.
+*/
+
+
+/*!
+ \fn BSymLink::BSymLink(const BEntry *entry)
+ \brief Creates a BSymLink object and initializes it to the symbolic link
+ referred to by the supplied BEntry.
+
+ \param entry The BEntry referring to the symbolic link.
+*/
+
+
+/*!
+ \fn BSymLink::BSymLink(const char *path)
+ \brief Creates a BSymLink object and initializes it to the symbolic link
+ referred to by the supplied path name.
+
+ \param path The path of the symbolic link.
+*/
+
+
+/*!
+ \fn BSymLink::BSymLink(const BDirectory *dir, const char *path)
+ \brief Creates a BSymLink object and initializes it to the symbolic link
+ referred to by the supplied path name relative to the specified
+ BDirectory.
+
+ \param dir The base BDirectory.
+ \param path The path of the symbolic link relative to \a dir.
+*/
+
+
+/*!
+ \fn BSymLink::~BSymLink()
+ \brief Destroys the object and frees all allocated resources.
+
+ If the BSymLink was properly initialized, the file descriptor of the
+ symbolic link is also closed.
+*/
+
+
+/*!
+ \fn ssize_t BSymLink::ReadLink(char *buffer, size_t size)
+ \brief Reads the contents of the symbolic link into \a buffer.
+
+ The string written to the buffer is guaranteed to be \c NULL terminated.
+
+ \param buffer The buffer to read the symlink's contents into.
+ \param size The size of \a buffer.
+
+ \return The number of bytes written into the buffer or an error code.
+ \retval B_BAD_VALUE \a buf was \c NULL or the object didn't refer to a
+ symbolic link.
+ \retval B_FILE_ERROR The object was not initialized.
+*/
+
+
+/*!
+ \fn ssize_t BSymLink::MakeLinkedPath(const char *dirPath, BPath *path)
+ \brief Combines a directory path and the contents of this symbolic link
to
+ form an absolute path.
+
+ \param dirPath The base directory path to combine with the symbolic
link.
+ \param path The BPath object to be set to the resulting absolute path.
+
+ \return The length of the resulting path name or an error code.
+ \retval B_BAD_VALUE \a dirPath or \a path was \c NULL or the object
didn't
+ refer to a symbolic link.
+ \retval B_FILE_ERROR The object was not initialized.
+ \retval B_NAME_TOO_LONG The resulting path name was too long to fit.
+*/
+
+
+/*!
+ \fn ssize_t BSymLink::MakeLinkedPath(const BDirectory *dir, BPath *path)
+ \brief Combines a directory path and the contents of this symbolic link
to
+ form an absolute path.
+
+ \param dir The base BDirectory object to combine with the symbolic link.
+ \param path the BPath object to be set to the resulting absolute path.
+
+ \return The length of the resulting path name or an error code.
+ \retval B_BAD_VALUE \a dir or \a path was \c NULL or the object didn't
+ refer to a symbolic link.
+ \retval B_FILE_ERROR The object was not initialized.
+ \retval B_NAME_TOO_LONG The resulting path name was too long to fit.
+*/
+
+
+/*!
+ \fn bool BSymLink::IsAbsolute()
+ \brief Returns whether or not the object refers to an absolute path.
+
+ /return \c true if the object is properly initialized and the symbolic
+ link refers to an absolute path, \c false otherwise.
+*/
+
+
+/*!
+ \fn int BSymLink::get_fd() const
+ \brief Returns the file descriptor of the BSymLink.
+
+ This method should be used instead of accessing the private \c fFd
member
+ of the BNode directly.
+
+ \return The object's file descriptor, or -1 if not properly initialized.
+*/
diff --git a/headers/os/storage/SymLink.h b/headers/os/storage/SymLink.h
index 3ba659e..89d3798 100644
--- a/headers/os/storage/SymLink.h
+++ b/headers/os/storage/SymLink.h
@@ -9,50 +9,44 @@
#include <Node.h>
#include <StorageDefs.h>
+
class BDirectory;
class BPath;
-
-/*!
- \class BSymLink
- \brief A symbolic link in the filesystem
-
- Provides an interface for manipulating symbolic links.
-
- \author <a href='mailto:bonefish@xxxxxxxxxxxx'>Ingo Weinhold</a>
-
- \version 0.0.0
-*/
class BSymLink : public BNode {
public:
- BSymLink();
- BSymLink(const BSymLink &link);
- BSymLink(const entry_ref *ref);
- BSymLink(const BEntry *entry);
- BSymLink(const char *path);
- BSymLink(const BDirectory *dir, const char *path);
- virtual ~BSymLink();
+ BSymLink();
+ BSymLink(const
BSymLink &link);
+ BSymLink(const
entry_ref *ref);
+ BSymLink(const
BEntry *entry);
+ BSymLink(const
char *path);
+ BSymLink(const
BDirectory *dir,
+ const
char *path);
+ virtual ~BSymLink();
- ssize_t ReadLink(char *buf, size_t size);
+ ssize_t ReadLink(char *buf,
size_t size);
- ssize_t MakeLinkedPath(const char *dirPath, BPath *path);
- ssize_t MakeLinkedPath(const BDirectory *dir, BPath *path);
+ ssize_t MakeLinkedPath(const
char *dirPath,
+
BPath *path);
+ ssize_t MakeLinkedPath(const
BDirectory *dir,
+
BPath *path);
- bool IsAbsolute();
+ bool IsAbsolute();
private:
- virtual void _MissingSymLink1();
- virtual void _MissingSymLink2();
- virtual void _MissingSymLink3();
- virtual void _MissingSymLink4();
- virtual void _MissingSymLink5();
- virtual void _MissingSymLink6();
+ virtual void _MissingSymLink1();
+ virtual void _MissingSymLink2();
+ virtual void _MissingSymLink3();
+ virtual void _MissingSymLink4();
+ virtual void _MissingSymLink5();
+ virtual void _MissingSymLink6();
- uint32 _reservedData[4];
- BEntry *fSecretEntry;
+ uint32 _reservedData[4];
+ BEntry* fSecretEntry;
private:
- int get_fd() const;
+ int get_fd() const;
};
+
#endif // _SYM_LINK_H
diff --git a/src/kits/storage/SymLink.cpp b/src/kits/storage/SymLink.cpp
index e56f654..fe3190b 100644
--- a/src/kits/storage/SymLink.cpp
+++ b/src/kits/storage/SymLink.cpp
@@ -8,11 +8,6 @@
*/
-/*! \file SymLink.cpp
- BSymLink implementation.
-*/
-
-
#include <new>
#include <string.h>
@@ -25,18 +20,17 @@
#include "storage_support.h"
+
using namespace std;
-//! Creates an uninitialized BSymLink object.
+// Creates an uninitialized BSymLink object.
BSymLink::BSymLink()
{
}
-//! Creates a copy of the supplied BSymLink.
-/*! \param link the BSymLink object to be copied
-*/
+// Creates a copy of the supplied BSymLink object.
BSymLink::BSymLink(const BSymLink &link)
:
BNode(link)
@@ -44,10 +38,8 @@ BSymLink::BSymLink(const BSymLink &link)
}
-/*! \brief Creates a BSymLink and initializes it to the symbolic link referred
- to by the supplied entry_ref.
- \param ref the entry_ref referring to the symbolic link
-*/
+// Creates a BSymLink object and initializes it to the symbolic link referred
+// to by the supplied entry_ref.
BSymLink::BSymLink(const entry_ref *ref)
:
BNode(ref)
@@ -55,20 +47,16 @@ BSymLink::BSymLink(const entry_ref *ref)
}
-/*! \brief Creates a BSymLink and initializes it to the symbolic link referred
- to by the supplied BEntry.
- \param entry the BEntry referring to the symbolic link
-*/
+// Creates a BSymLink object and initializes it to the symbolic link referred
+// to by the supplied BEntry.
BSymLink::BSymLink(const BEntry *entry)
: BNode(entry)
{
}
-/*! \brief Creates a BSymLink and initializes it to the symbolic link referred
- to by the supplied path name.
- \param path the symbolic link's path name
-*/
+// Creates a BSymLink object and initializes it to the symbolic link referred
+// to by the supplied path name.
BSymLink::BSymLink(const char *path)
:
BNode(path)
@@ -76,12 +64,8 @@ BSymLink::BSymLink(const char *path)
}
-/*! \brief Creates a BSymLink and initializes it to the symbolic link referred
- to by the supplied path name relative to the specified BDirectory.
- \param dir the BDirectory, relative to which the symbolic link's path
name
- is given
- \param path the symbolic link's path name relative to \a dir
-*/
+// Creates a BSymLink object and initializes it to the symbolic link referred
+// to by the supplied path name relative to the specified BDirectory.
BSymLink::BSymLink(const BDirectory *dir, const char *path)
:
BNode(dir, path)
@@ -89,31 +73,19 @@ BSymLink::BSymLink(const BDirectory *dir, const char *path)
}
-//! Frees all allocated resources.
-/*! If the BSymLink is properly initialized, the symbolic link's file
- descriptor is closed.
-*/
+// Destroys the object and frees all allocated resources.
BSymLink::~BSymLink()
{
}
-//! Reads the contents of the symbolic link into a buffer.
-/*! The string written to the buffer will be null-terminated.
- \param buf the buffer
- \param size the size of the buffer
- \return
- - the number of bytes written into the buffer
- - \c B_BAD_VALUE: \c NULL \a buf or the object doesn't refer to a
symbolic
- link.
- - \c B_FILE_ERROR: The object is not initialized.
- - some other error code
-*/
+// Reads the contents of the symbolic link into a buffer.
ssize_t
BSymLink::ReadLink(char *buffer, size_t size)
{
- if (!buffer)
+ if (buffer == NULL)
return B_BAD_VALUE;
+
if (InitCheck() != B_OK)
return B_FILE_ERROR;
@@ -125,57 +97,40 @@ BSymLink::ReadLink(char *buffer, size_t size)
// null-terminate
if (linkLen >= size)
return B_BUFFER_OVERFLOW;
+
buffer[linkLen] = '\0';
return linkLen;
}
-/*! \brief Combines a directory path and the contents of this symbolic link
to
- an absolute path.
- \param dirPath the path name of the directory
- \param path the BPath object to be set to the resulting path name
- \return
- - \c the length of the resulting path name,
- - \c B_BAD_VALUE: \c NULL \a dirPath or \a path or the object doesn't
- refer to a symbolic link.
- - \c B_FILE_ERROR: The object is not initialized.
- - \c B_NAME_TOO_LONG: The resulting path name is too long.
- - some other error code
-*/
+// Combines a directory path and the contents of this symbolic link to form an
+// absolute path.
ssize_t
BSymLink::MakeLinkedPath(const char *dirPath, BPath *path)
{
- // BeOS seems to convert the dirPath to a BDirectory, which causes
links to
- // be resolved.
- // This does also mean that the dirPath must exist!
- if (!dirPath || !path)
+ // BeOS seems to convert the dirPath to a BDirectory, which causes links
+ // to be resolved. This means that the dirPath must exist!
+ if (dirPath == NULL || path == NULL)
return B_BAD_VALUE;
+
BDirectory dir(dirPath);
ssize_t result = dir.InitCheck();
if (result == B_OK)
result = MakeLinkedPath(&dir, path);
+
return result;
}
-/*! \brief Combines a directory path and the contents of this symbolic link
to
- an absolute path.
- \param dir the BDirectory referring to the directory
- \param path the BPath object to be set to the resulting path name
- \return
- - \c the length of the resulting path name,
- - \c B_BAD_VALUE: \c NULL \a dir or \a path or the object doesn't
- refer to a symbolic link.
- - \c B_FILE_ERROR: The object is not initialized.
- - \c B_NAME_TOO_LONG: The resulting path name is too long.
- - some other error code
-*/
+// Combines a directory path and the contents of this symbolic link to form an
+// absolute path.
ssize_t
BSymLink::MakeLinkedPath(const BDirectory *dir, BPath *path)
{
- if (!dir || !path)
+ if (dir == NULL || path == NULL)
return B_BAD_VALUE;
+
char contents[B_PATH_NAME_LENGTH];
ssize_t result = ReadLink(contents, sizeof(contents));
if (result >= 0) {
@@ -183,19 +138,16 @@ BSymLink::MakeLinkedPath(const BDirectory *dir, BPath
*path)
result = path->SetTo(contents);
else
result = path->SetTo(dir, contents);
+
if (result == B_OK)
result = strlen(path->Path());
}
+
return result;
}
-//! Returns whether this BSymLink refers to an absolute link.
-/*! /return
- - \c true, if the object is properly initialized and the symbolic link
it
- refers to is an absolute link,
- - \c false, otherwise.
-*/
+// Returns whether or not the object refers to an absolute path.
bool
BSymLink::IsAbsolute()
{
@@ -203,6 +155,7 @@ BSymLink::IsAbsolute()
bool result = (ReadLink(contents, sizeof(contents)) >= 0);
if (result)
result = BPrivate::Storage::is_absolute_path(contents);
+
return result;
}
@@ -215,10 +168,7 @@ void BSymLink::_MissingSymLink5() {}
void BSymLink::_MissingSymLink6() {}
-//! Returns the BSymLink's file descriptor.
-/*! To be used instead of accessing the BNode's private \c fFd member directly.
- \return the file descriptor, or -1, if not properly initialized.
-*/
+// Returns the file descriptor of the BSymLink.
int
BSymLink::get_fd() const
{
Other related posts: