1 /*********************************************************************/ 2 // dar - disk archive - a backup/restoration program 3 // Copyright (C) 2002-2052 Denis Corbin 4 // 5 // This program is free software; you can redistribute it and/or 6 // modify it under the terms of the GNU General Public License 7 // as published by the Free Software Foundation; either version 2 8 // of the License, or (at your option) any later version. 9 // 10 // This program is distributed in the hope that it will be useful, 11 // but WITHOUT ANY WARRANTY; without even the implied warranty of 12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 // GNU General Public License for more details. 14 // 15 // You should have received a copy of the GNU General Public License 16 // along with this program; if not, write to the Free Software 17 // Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 18 // 19 // to contact the author : http://dar.linux.free.fr/email.html 20 /*********************************************************************/ 21 22 // NOTE : The following comments are used by doxygen to generate the documentation of reference 23 24 /// \mainpage 25 /// You will find here the reference documentation for the dar and libdar source code, split in several "modules". 26 /// - API module: contains all information for using libdar within your program 27 /// - Tools module: contains some routines you may like to have a look at (but using them with caution) 28 /// - Private module: contains all libdar internal documentation, it is not necessary to read it to be able to use libdar 29 /// - CMDLINE module: contains the documentation for command-line tools, you might want to have a look for illustration of library usage. 30 /// . 31 /// CMDLINE module is out of any namespace as it is not inteded to be used by external application. All other symbols are part of the libdar namespace. 32 /// 33 /// Please not that an API tutorial is also available for a higher view of this library. 34 35 36 /// \defgroup API API 37 /// \brief APlication Interface 38 /// 39 /// This gathers all symbols that may be accessed from an external 40 /// program. Other symbols are not as much documented, and 41 /// may change or be removed without any warning or backward 42 /// compatibility support. So only use the function, macro, types, 43 /// classes... defined as member of the API module in you external programs. 44 45 46 /// \defgroup Private Private 47 /// \brief Symbols that are not to be used by external software. 48 /// 49 /// never use threses symboles (function, macro, variables, types, etc.) 50 /// they are not intended to be used by external programs 51 /// and may change or disapear without any warning or backward 52 /// compatibility. Some are however documented for libdar development ease. 53 54 55 /// \file libdar.hpp 56 /// \brief the main file of the libdar API definitions 57 /// \ingroup API 58 59 60 61 #ifndef LIBDAR_HPP 62 #define LIBDAR_HPP 63 64 #include "../my_config.h" 65 66 extern "C" 67 { 68 #if MUTEX_WORKS 69 #if HAVE_PTHREAD_H 70 #include <pthread.h> 71 #endif 72 #endif 73 } 74 75 76 #include <string> 77 #include "compressor.hpp" 78 #include "path.hpp" 79 #include "mask.hpp" 80 #include "integers.hpp" 81 #include "infinint.hpp" 82 #include "statistics.hpp" 83 #include "user_interaction.hpp" 84 #include "deci.hpp" 85 #include "archive.hpp" 86 #include "crypto.hpp" 87 #include "thread_cancellation.hpp" 88 #include "compile_time_features.hpp" 89 #include "capabilities.hpp" 90 91 /// \addtogroup API 92 /// @{ 93 94 /// The following macro are used in the "exception" argument of the *_noexcept() functions 95 #define LIBDAR_XXXXXXXX 96 97 /// normal return no exception has been thrown 98 #define LIBDAR_NOEXCEPT 0 99 /// memory has been exhausted 100 #define LIBDAR_EMEMORY 1 101 /// internal bug error. 102 #define LIBDAR_EBUG 2 103 /// division by zero or other arithmetic error 104 #define LIBDAR_EINFININT 3 105 /// limitint overflow 106 #define LIBDAR_ELIMITINT 4 107 /// range error 108 #define LIBDAR_ERANGE 5 109 /// decimal representation error 110 #define LIBDAR_EDECI 6 111 /// feature not (yet) implemented 112 #define LIBDAR_EFEATURE 7 113 /// hardware failure 114 #define LIBDAR_EHARDWARE 8 115 /// user has aborted the operation 116 #define LIBDAR_EUSER_ABORT 9 117 /// data inconsistency, error concerning the treated data 118 #define LIBDAR_EDATA 10 119 /// inter slice script failure 120 #define LIBDAR_ESCRIPT 11 121 /// libdar invalid call (wrong argument given to call, etc.) 122 #define LIBDAR_ELIBCALL 12 123 /// unknown error 124 #define LIBDAR_UNKNOWN 13 125 /// feature not activated at compilation time 126 #define LIBDAR_ECOMPILATION 14 127 /// thread cancellation has been requested 128 #define LIBDAR_THREAD_CANCEL 15 129 /// @} 130 131 /// libdar namespace encapsulate all libdar symbols 132 namespace libdar 133 { 134 /// \addtogroup API 135 /// @{ 136 137 138 /// libdar Major version defined at compilation time 139 const U_I LIBDAR_COMPILE_TIME_MAJOR = 5; 140 /// libdar Medium version defined at compilation time 141 const U_I LIBDAR_COMPILE_TIME_MEDIUM = 12; 142 /// libdar Minor version defined at compilation time 143 const U_I LIBDAR_COMPILE_TIME_MINOR = 1; 144 145 //////////////////////////////////////////////////////////////////////// 146 // LIBDAR INITIALIZATION METHODS // 147 // // 148 // A FUNCTION OF THE get_version*() FAMILY *MUST* BE CALLED // 149 // BEFORE ANY OTHER FUNCTION OF THIS LIBRARY // 150 // // 151 // CLIENT PROGRAM MUST CHECK THAT THE MAJOR NUMBER RETURNED // 152 // BY THIS CALL IS NOT GREATER THAN THE VERSION USED AT COMPILATION // 153 // TIME. IF SO, THE PROGRAM MUST ABORT AND RETURN A WARNING TO THE // 154 // USER TELLING THE DYNAMICALLY LINKED VERSION IS TOO RECENT AND NOT // 155 // COMPATIBLE WITH THIS SOFTWARE. THE MESSAGE MUST INVITE THE USER // 156 // TO UPGRADE HIS SOFTWARE WITH A MORE RECENT VERSION COMPATIBLE WITH // 157 // THIS LIBDAR RELEASE. // 158 //////////////////////////////////////////////////////////////////////// 159 160 /// return the libdar version, and make libdar initialization (may throw Exceptions) 161 162 /// It is mandatory to call this function (or another one of the get_version* family) 163 /// \param[out] major the major number of the version 164 /// \param[out] medium the medium number of the version 165 /// \param[out] minor the minor number of the version 166 /// \param[in] init_libgcrypt whether to initialize libgcrypt if not already done (not used if libcrypt is not linked with libdar) 167 /// \note the calling application must match that the major function 168 /// is the same as the libdar used at compilation time. See API tutorial for a 169 /// sample code. 170 extern void get_version(U_I & major, U_I & medium, U_I & minor, bool init_libgcrypt = true); 171 172 /// return the libdar version, and make libdar initialization (does not throw exceptions) 173 174 /// It is mandatory to call this function (or another one of the get_version* family) 175 /// \param[out] major the major number of the version 176 /// \param[out] medium the medium number of the version 177 /// \param[out] minor the minor number of the version 178 /// \param[out] exception is to be compared with the LIBDAR_* macro to know whether the call succeeded 179 /// \param[out] except_msg in case exception is not equal to LIBDAR_NOEXCEPT this argument contains 180 /// \param[in] init_libgcrypt whether to initialize libgcrypt if not already done (not used if libcrypt is not linked with libdar) 181 /// a human readable explaination of the error met. 182 /// \note the calling application must match that the major function 183 /// is the same as the libdar used at compilation time. See API tutorial for a 184 /// sample code. 185 extern void get_version_noexcept(U_I & major, U_I & medium, U_I & minor, U_16 & exception, std::string & except_msg, bool init_libgcrypt = true); 186 187 188 /////////////////////////////////////////////// 189 // CLOSING/CLEANING LIBDAR // 190 /////////////////////////////////////////////// 191 192 // while libdar has only a single boolean as global variable 193 // that defines whether the library is initialized or not 194 // it must proceed to mutex, and dependent libraries initializations 195 // (liblzo, libgcrypt, etc.), which is done during the get_version() call 196 // Some library also need to clear some data so the following call 197 // is provided in that aim and must be called when libdar will no more 198 // be used by the application. 199 200 extern void close_and_clean(); 201 202 203 ////////// 204 // WRAPPER FUNCTIONS AROUND archive class methods to trap exceptions and convert them in error code and message 205 // these are intended for C program/programmers not enough confident with C++. 206 // 207 // FOR LIBDAR C++ APPLICATIONS, YOU WOULD RATHER USE THE archive C++ CLASS THAN THESE FOLLOWING WRAPPERS 208 // 209 ////////// 210 211 212 /// this is a wrapper around the archive constructor known as the "read" constructor 213 214 /// check the archive class for details 215 /// for an explaination of the two extra arguments exception and except_msg check 216 /// the get_version_noexcept function 217 extern archive* open_archive_noexcept(user_interaction & dialog, 218 const path & chem, const std::string & basename, 219 const std::string & extension, 220 const archive_options_read & options, 221 U_16 & exception, 222 std::string & except_msg); 223 224 225 /// this is a wrapper around the archive constructor known as the "create" constructor 226 227 /// check the archive class for details 228 /// for an explaination of the two extra arguments exception and except_msg check 229 /// the get_version_noexcept function 230 extern archive *create_archive_noexcept(user_interaction & dialog, 231 const path & fs_root, 232 const path & sauv_path, 233 const std::string & filename, 234 const std::string & extension, 235 const archive_options_create & options, 236 statistics * progressive_report, 237 U_16 & exception, 238 std::string & except_msg); 239 240 241 242 /// this is a wrapper around the archive constructor known as the "isolate" constructor 243 244 /// check the archive class for details 245 /// for an explaination of the two extra arguments exception and except_msg check 246 /// the get_version_noexcept function 247 extern archive *isolate_archive_noexcept(user_interaction & dialog, 248 archive *ptr, 249 const path &sauv_path, 250 const std::string & filename, 251 const std::string & extension, 252 const archive_options_isolate & options, 253 U_16 & exception, 254 std::string & except_msg); 255 256 /// this is a wrapper around the archive constructor known as the "merging" constructor 257 258 /// check the archive class for details 259 /// for an explaination of the two extra arguments exception and except_msg check 260 /// the get_version_noexcept function 261 extern archive *merge_archive_noexcept(user_interaction & dialog, 262 const path & sauv_path, 263 archive *ref_arch1, 264 const std::string & filename, 265 const std::string & extension, 266 const archive_options_merge & options, 267 statistics * progressive_report, 268 U_16 & exception, 269 std::string & except_msg); 270 271 272 /// this is wrapper around the archive destructor 273 274 /// check the archive class for details 275 /// for an explaination of the two extra arguments exception and except_msg check 276 /// the get_version_noexcept function 277 extern void close_archive_noexcept(archive *ptr, 278 U_16 & exception, 279 std::string & except_msg); 280 281 282 /// this is wrapper around the op_extract method 283 284 /// check the archive class for details 285 /// for an explaination of the two extra arguments exception and except_msg check 286 /// the get_version_noexcept function 287 extern statistics op_extract_noexcept(user_interaction & dialog, 288 archive *ptr, 289 const path &fs_root, 290 const archive_options_extract & options, 291 statistics * progressive_report, 292 U_16 & exception, 293 std::string & except_msg); 294 295 296 /// this is wrapper around the op_listing method 297 298 /// check the archive class for details 299 /// for an explaination of the two extra arguments exception and except_msg check 300 /// the get_version_noexcept function 301 extern void op_listing_noexcept(user_interaction & dialog, 302 archive *ptr, 303 const archive_options_listing & options, 304 U_16 & exception, 305 std::string & except_msg); 306 307 308 /// this is wrapper around the op_diff method 309 310 /// check the archive class for details 311 /// for an explaination of the two extra arguments exception and except_msg check 312 /// the get_version_noexcept function 313 extern statistics op_diff_noexcept(user_interaction & dialog, 314 archive *ptr, 315 const path & fs_root, 316 const archive_options_diff & options, 317 statistics * progressive_report, 318 U_16 & exception, 319 std::string & except_msg); 320 321 322 /// this is wrapper around the op_test method 323 324 /// check the archive class for details 325 /// for an explaination of the two extra arguments exception and except_msg check 326 /// the get_version_noexcept function 327 extern statistics op_test_noexcept(user_interaction & dialog, 328 archive *ptr, 329 const archive_options_test & options, 330 statistics * progressive_report, 331 U_16 & exception, 332 std::string & except_msg); 333 334 335 /// this is wrapper around the get_children_of method 336 337 /// check the archive class for details 338 /// for an explaination of the two extra arguments exception and except_msg check 339 /// the get_version_noexcept function 340 extern bool get_children_of_noexcept(user_interaction & dialog, 341 archive *ptr, 342 const std::string & dir, 343 U_16 & exception, 344 std::string & except_msg); 345 346 347 348 /////////////////////////////////////////////// 349 // TOOLS ROUTINES // 350 /////////////////////////////////////////////// 351 352 353 /// routine provided to convert std::string to char * 354 355 /// \param[in] x the string to convert 356 /// \param[out] exception the return status of the call 357 /// \param[out] except_msg the message taken from the caught exception in case of error 358 /// for an explaination of the two last arguments exception and except_msg check 359 /// the get_version_noexcept function 360 /// \return the address of a newly allocated memory 361 /// which must be released calling the "delete []" 362 /// operator when no more needed. 363 /// \return nullptr in case of error 364 extern char *libdar_str2charptr_noexcept(const std::string & x, U_16 & exception, std::string & except_msg); 365 366 /////////////////////////////////////////////// 367 // THREAD CANCELLATION ROUTINES // 368 /////////////////////////////////////////////// 369 370 #if MUTEX_WORKS 371 /// thread cancellation activation 372 373 /// ask that any libdar code running in the thread given as argument be cleanly aborted 374 /// when the execution will reach the next libdar checkpoint 375 /// \param[in] tid is the Thread ID to cancel libdar in 376 /// \param[in] immediate whether to cancel thread immediately or just signal the request to the thread 377 /// \param[in] flag an arbitrary value passed as-is through libdar cancel_thread(pthread_t tid,bool immediate=true,U_64 flag=0)378 inline extern void cancel_thread(pthread_t tid, bool immediate = true, U_64 flag = 0) { thread_cancellation::cancel(tid, immediate, flag); } 379 380 /// consultation of the cancellation status of a given thread 381 382 /// \param[in] tid is the tid of the thread to get status about 383 /// \return false if no cancellation has been requested for the given thread cancel_status(pthread_t tid)384 inline extern bool cancel_status(pthread_t tid) { return thread_cancellation::cancel_status(tid); } 385 386 /// thread cancellation deactivation 387 388 /// abort the thread cancellation for the given thread 389 /// \return false if no thread cancellation was under process for that thread 390 /// or if there is no more pending cancellation (thread has already been canceled). cancel_clear(pthread_t tid)391 inline extern bool cancel_clear(pthread_t tid) { return thread_cancellation::clear_pending_request(tid); } 392 #endif 393 394 395 /// @} 396 397 } // end of namespace 398 399 #endif 400