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 This function does not return the number of bytes written into 117 the provided buffer. It returns the length of the symlink's 118 contents, even if that contents does not fit within the 119 provided buffer. If the buffer cannot contain the entire 120 contents then it will be truncated to \a size. 121 122 \param buffer The buffer to read the symlink's contents into. 123 \param size The size of \a buffer. 124 125 \return The length of the symlink's contents or an error code. 126 \retval B_BAD_VALUE \a buf was \c NULL or the object didn't refer to a 127 symbolic link. 128 \retval B_FILE_ERROR The object was not initialized. 129 130 \since BeOS R3 131*/ 132 133 134/*! 135 \fn ssize_t BSymLink::MakeLinkedPath(const char* dirPath, BPath* path) 136 \brief Combines a directory path and the contents of this symbolic link to 137 form an absolute path. 138 139 \param dirPath The base directory path to combine with the symbolic link. 140 \param path The BPath object to be set to the resulting absolute path. 141 142 \return The length of the resulting path name or an error code. 143 \retval B_BAD_VALUE \a dirPath or \a path was \c NULL or the object didn't 144 refer to a symbolic link. 145 \retval B_FILE_ERROR The object was not initialized. 146 \retval B_NAME_TOO_LONG The resulting path name was too long to fit. 147 148 \since BeOS R3 149*/ 150 151 152/*! 153 \fn ssize_t BSymLink::MakeLinkedPath(const BDirectory* dir, BPath* path) 154 \brief Combines a directory path and the contents of this symbolic link to 155 form an absolute path. 156 157 \param dir The base BDirectory object to combine with the symbolic link. 158 \param path the BPath object to be set to the resulting absolute path. 159 160 \return The length of the resulting path name or an error code. 161 \retval B_BAD_VALUE \a dir or \a path was \c NULL or the object didn't 162 refer to a symbolic link. 163 \retval B_FILE_ERROR The object was not initialized. 164 \retval B_NAME_TOO_LONG The resulting path name was too long to fit. 165 166 \since BeOS R3 167*/ 168 169 170/*! 171 \fn bool BSymLink::IsAbsolute() 172 \brief Returns whether or not the object refers to an absolute path. 173 174 /return \c true if the object is properly initialized and the symbolic 175 link refers to an absolute path, \c false otherwise. 176 177 \since BeOS R3 178*/ 179