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 * John Scipione, jscipione@gmail.com 8 * Ingo Weinhold, bonefish@users.sf.net 9 * 10 * Corresponds to: 11 * headers/os/storage/SymLink.h hrev45306 12 * src/kits/storage/SymLink.cpp hrev45306 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 32 33/*! 34 \fn BSymLink::BSymLink() 35 \brief Creates an uninitialized BSymLink object. 36*/ 37 38 39/*! 40 \fn BSymLink::BSymLink(const BSymLink &link) 41 \brief Creates a copy of the supplied BSymLink object. 42 43 \param link The BSymLink object to be copied. 44*/ 45 46 47/*! 48 \fn BSymLink::BSymLink(const entry_ref *ref) 49 \brief Creates a BSymLink object and initializes it to the symbolic link 50 referred to by the supplied entry_ref. 51 52 \param ref the entry_ref referring to the symbolic link. 53*/ 54 55 56/*! 57 \fn BSymLink::BSymLink(const BEntry *entry) 58 \brief Creates a BSymLink object and initializes it to the symbolic link 59 referred to by the supplied BEntry. 60 61 \param entry The BEntry referring to the symbolic link. 62*/ 63 64 65/*! 66 \fn BSymLink::BSymLink(const char *path) 67 \brief Creates a BSymLink object and initializes it to the symbolic link 68 referred to by the supplied path name. 69 70 \param path The path of the symbolic link. 71*/ 72 73 74/*! 75 \fn BSymLink::BSymLink(const BDirectory *dir, const char *path) 76 \brief Creates a BSymLink object and initializes it to the symbolic link 77 referred to by the supplied path name relative to the specified 78 BDirectory. 79 80 \param dir The base BDirectory. 81 \param path The path of the symbolic link relative to \a dir. 82*/ 83 84 85/*! 86 \fn BSymLink::~BSymLink() 87 \brief Destroys the object and frees all allocated resources. 88 89 If the BSymLink was properly initialized, the file descriptor of the 90 symbolic link is also closed. 91*/ 92 93 94/*! 95 \fn ssize_t BSymLink::ReadLink(char *buffer, size_t size) 96 \brief Reads the contents of the symbolic link into \a buffer. 97 98 The string written to the buffer is guaranteed to be \c NULL terminated. 99 100 \param buffer The buffer to read the symlink's contents into. 101 \param size The size of \a buffer. 102 103 \return The number of bytes written into the buffer or an error code. 104 \retval B_BAD_VALUE \a buf was \c NULL or the object didn't refer to a 105 symbolic link. 106 \retval B_FILE_ERROR The object was not initialized. 107*/ 108 109 110/*! 111 \fn ssize_t BSymLink::MakeLinkedPath(const char *dirPath, BPath *path) 112 \brief Combines a directory path and the contents of this symbolic link to 113 form an absolute path. 114 115 \param dirPath The base directory path to combine with the symbolic link. 116 \param path The BPath object to be set to the resulting absolute path. 117 118 \return The length of the resulting path name or an error code. 119 \retval B_BAD_VALUE \a dirPath or \a path was \c NULL or the object didn't 120 refer to a symbolic link. 121 \retval B_FILE_ERROR The object was not initialized. 122 \retval B_NAME_TOO_LONG The resulting path name was too long to fit. 123*/ 124 125 126/*! 127 \fn ssize_t BSymLink::MakeLinkedPath(const BDirectory *dir, BPath *path) 128 \brief Combines a directory path and the contents of this symbolic link to 129 form an absolute path. 130 131 \param dir The base BDirectory object to combine with the symbolic link. 132 \param path the BPath object to be set to the resulting absolute path. 133 134 \return The length of the resulting path name or an error code. 135 \retval B_BAD_VALUE \a dir or \a path was \c NULL or the object didn't 136 refer to a symbolic link. 137 \retval B_FILE_ERROR The object was not initialized. 138 \retval B_NAME_TOO_LONG The resulting path name was too long to fit. 139*/ 140 141 142/*! 143 \fn bool BSymLink::IsAbsolute() 144 \brief Returns whether or not the object refers to an absolute path. 145 146 /return \c true if the object is properly initialized and the symbolic 147 link refers to an absolute path, \c false otherwise. 148*/ 149 150 151/*! 152 \fn int BSymLink::get_fd() const 153 \brief Returns the file descriptor of the BSymLink. 154 155 This method should be used instead of accessing the private \c fFd member 156 of the BNode directly. 157 158 \return The object's file descriptor, or -1 if not properly initialized. 159*/ 160