docs/user/storage/SymLink.dox

   1 /*
   2  * Copyright 2002-2014 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Tyler Dauwalder
   7  *              John Scipione, jscipione@gmail.com
   8  *              Ingo Weinhold, bonefish@users.sf.net
   9  *
  10  * Corresponds to:
  11  *              headers/os/storage/SymLink.h    hrev47402
  12  *              src/kits/storage/SymLink.cpp    hrev47402
  13  */
  14
  15
  16 /*!
  17         \file SymLink.h
  18         \ingroup storage
  19         \ingroup libbe
  20         \brief Provides the BSymLink class.
  21 */
  22
  23
  24 /*!
  25         \class BSymLink
  26         \ingroup storage
  27         \ingroup libbe
  28         \brief Provides an interface for creating, manipulating, and accessing
  29                the contents of symbolic links.
  30
  31         \since BeOS R3
  32 */
  33
  34
  35 /*!
  36         \fn BSymLink::BSymLink()
  37         \brief Creates an uninitialized BSymLink object.
  38
  39         \since BeOS R3
  40 */
  41
  42
  43 /*!
  44         \fn BSymLink::BSymLink(const BSymLink& other)
  45         \brief Creates a copy of the supplied BSymLink object.
  46
  47         \param other The BSymLink object to be copied.
  48
  49         \since BeOS R3
  50 */
  51
  52
  53 /*!
  54         \fn BSymLink::BSymLink(const entry_ref* ref)
  55         \brief Creates a BSymLink object and initializes it to the symbolic link
  56                referred to by the supplied entry_ref.
  57
  58         \param ref the entry_ref referring to the symbolic link.
  59
  60         \since BeOS R3
  61 */
  62
  63
  64 /*!
  65         \fn BSymLink::BSymLink(const BEntry* entry)
  66         \brief Creates a BSymLink object and initializes it to the symbolic link
  67                referred to by the supplied BEntry.
  68
  69         \param entry The BEntry referring to the symbolic link.
  70
  71         \since BeOS R3
  72 */
  73
  74
  75 /*!
  76         \fn BSymLink::BSymLink(const char* path)
  77         \brief Creates a BSymLink object and initializes it to the symbolic link
  78                referred to by the supplied path name.
  79
  80         \param path The path of the symbolic link.
  81
  82         \since BeOS R3
  83 */
  84
  85
  86 /*!
  87         \fn BSymLink::BSymLink(const BDirectory* dir, const char* path)
  88         \brief Creates a BSymLink object and initializes it to the symbolic link
  89                referred to by the supplied path name relative to the specified
  90                BDirectory.
  91
  92         \param dir The base BDirectory.
  93         \param path The path of the symbolic link relative to \a dir.
  94
  95         \since BeOS R3
  96 */
  97
  98
  99 /*!
 100         \fn BSymLink::~BSymLink()
 101         \brief Destroys the object and frees all allocated resources.
 102
 103         If the BSymLink was properly initialized, the file descriptor of the
 104         symbolic link is also closed.
 105
 106         \since BeOS R3
 107 */
 108
 109
 110 /*!
 111         \fn ssize_t BSymLink::ReadLink(char* buffer, size_t size)
 112         \brief Reads the contents of the symbolic link into \a buffer.
 113
 114         The string written to the buffer is guaranteed to be \c NULL terminated.
 115
 116         \param buffer The buffer to read the symlink's contents into.
 117         \param size The size of \a buffer.
 118
 119         \return The number of bytes written into the buffer or an error code.
 120         \retval B_BAD_VALUE \a buf was \c NULL or the object didn't refer to a
 121                 symbolic link.
 122         \retval B_FILE_ERROR The object was not initialized.
 123
 124         \since BeOS R3
 125 */
 126
 127
 128 /*!
 129         \fn ssize_t BSymLink::MakeLinkedPath(const char* dirPath, BPath* path)
 130         \brief Combines a directory path and the contents of this symbolic link to
 131                form an absolute path.
 132
 133         \param dirPath The base directory path to combine with the symbolic link.
 134         \param path The BPath object to be set to the resulting absolute path.
 135
 136         \return The length of the resulting path name or an error code.
 137         \retval B_BAD_VALUE \a dirPath or \a path was \c NULL or the object didn't
 138                 refer to a symbolic link.
 139         \retval B_FILE_ERROR The object was not initialized.
 140         \retval B_NAME_TOO_LONG The resulting path name was too long to fit.
 141
 142         \since BeOS R3
 143 */
 144
 145
 146 /*!
 147         \fn ssize_t BSymLink::MakeLinkedPath(const BDirectory* dir, BPath* path)
 148         \brief Combines a directory path and the contents of this symbolic link to
 149                form an absolute path.
 150
 151         \param dir The base BDirectory object to combine with the symbolic link.
 152         \param path the BPath object to be set to the resulting absolute path.
 153
 154         \return The length of the resulting path name or an error code.
 155         \retval B_BAD_VALUE \a dir or \a path was \c NULL or the object didn't
 156                 refer to a symbolic link.
 157         \retval B_FILE_ERROR The object was not initialized.
 158         \retval B_NAME_TOO_LONG The resulting path name was too long to fit.
 159
 160         \since BeOS R3
 161 */
 162
 163
 164 /*!
 165         \fn bool BSymLink::IsAbsolute()
 166         \brief Returns whether or not the object refers to an absolute path.
 167
 168         /return \c true if the object is properly initialized and the symbolic
 169                 link refers to an absolute path, \c false otherwise.
 170
 171         \since BeOS R3
 172 */