Aren/haiku
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add BSymLink class docs to Haiku Book

Browse Source
This commit is contained in:
John Scipione 2013-02-20 16:20:53 -05:00
parent 29f51b3431
commit 434716ced8
3 changed files with 216 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

159
docs/user/storage/SymLink.dox Normal file
View File

@ -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@gmail.com
* Ingo Weinhold, bonefish@users.sf.net
*
* 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.
*/

56
headers/os/storage/SymLink.h
View File

@ -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@users.sf.net'>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

114
src/kits/storage/SymLink.cpp
View File

@ -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
{