1 /* 2 * Copyright (C) the libgit2 contributors. All rights reserved. 3 * 4 * This file is part of libgit2, distributed under the GNU GPL v2 with 5 * a Linking Exception. For full terms see the included COPYING file. 6 */ 7 #ifndef INCLUDE_git_common_h__ 8 #define INCLUDE_git_common_h__ 9 10 #include <time.h> 11 #include <stdlib.h> 12 13 #ifdef __cplusplus 14 # define GIT_BEGIN_DECL extern "C" { 15 # define GIT_END_DECL } 16 #else 17 /** Start declarations in C mode */ 18 # define GIT_BEGIN_DECL /* empty */ 19 /** End declarations in C mode */ 20 # define GIT_END_DECL /* empty */ 21 #endif 22 23 #if defined(_MSC_VER) && _MSC_VER < 1800 24 # include <stdint.h> 25 #elif !defined(__CLANG_INTTYPES_H) 26 # include <inttypes.h> 27 #endif 28 29 #ifdef DOCURIUM 30 /* 31 * This is so clang's doc parser acknowledges comments on functions 32 * with size_t parameters. 33 */ 34 typedef size_t size_t; 35 #endif 36 37 /** Declare a public function exported for application use. */ 38 #if __GNUC__ >= 4 39 # define GIT_EXTERN(type) extern \ 40 __attribute__((visibility("default"))) \ 41 type 42 #elif defined(_MSC_VER) 43 # define GIT_EXTERN(type) __declspec(dllexport) type __cdecl 44 #else 45 # define GIT_EXTERN(type) extern type 46 #endif 47 48 /** Declare a callback function for application use. */ 49 #if defined(_MSC_VER) 50 # define GIT_CALLBACK(name) (__cdecl *name) 51 #else 52 # define GIT_CALLBACK(name) (*name) 53 #endif 54 55 /** Declare a function as deprecated. */ 56 #if defined(__GNUC__) 57 # define GIT_DEPRECATED(func) \ 58 __attribute__((deprecated)) \ 59 __attribute__((used)) \ 60 func 61 #elif defined(_MSC_VER) 62 # define GIT_DEPRECATED(func) __declspec(deprecated) func 63 #else 64 # define GIT_DEPRECATED(func) func 65 #endif 66 67 /** Declare a function's takes printf style arguments. */ 68 #ifdef __GNUC__ 69 # define GIT_FORMAT_PRINTF(a,b) __attribute__((format (printf, a, b))) 70 #else 71 # define GIT_FORMAT_PRINTF(a,b) /* empty */ 72 #endif 73 74 #if (defined(_WIN32)) && !defined(__CYGWIN__) 75 #define GIT_WIN32 1 76 #endif 77 78 #ifdef __amigaos4__ 79 #include <netinet/in.h> 80 #endif 81 82 /** 83 * @file git2/common.h 84 * @brief Git common platform definitions 85 * @defgroup git_common Git common platform definitions 86 * @ingroup Git 87 * @{ 88 */ 89 90 GIT_BEGIN_DECL 91 92 /** 93 * The separator used in path list strings (ie like in the PATH 94 * environment variable). A semi-colon ";" is used on Windows and 95 * AmigaOS, and a colon ":" for all other systems. 96 */ 97 #if defined(GIT_WIN32) || defined(AMIGA) 98 #define GIT_PATH_LIST_SEPARATOR ';' 99 #else 100 #define GIT_PATH_LIST_SEPARATOR ':' 101 #endif 102 103 /** 104 * The maximum length of a valid git path. 105 */ 106 #define GIT_PATH_MAX 4096 107 108 /** 109 * The string representation of the null object ID. 110 */ 111 #define GIT_OID_HEX_ZERO "0000000000000000000000000000000000000000" 112 113 /** 114 * Return the version of the libgit2 library 115 * being currently used. 116 * 117 * @param major Store the major version number 118 * @param minor Store the minor version number 119 * @param rev Store the revision (patch) number 120 * @return 0 on success or an error code on failure 121 */ 122 GIT_EXTERN(int) git_libgit2_version(int *major, int *minor, int *rev); 123 124 /** 125 * Combinations of these values describe the features with which libgit2 126 * was compiled 127 */ 128 typedef enum { 129 /** 130 * If set, libgit2 was built thread-aware and can be safely used from multiple 131 * threads. 132 */ 133 GIT_FEATURE_THREADS = (1 << 0), 134 /** 135 * If set, libgit2 was built with and linked against a TLS implementation. 136 * Custom TLS streams may still be added by the user to support HTTPS 137 * regardless of this. 138 */ 139 GIT_FEATURE_HTTPS = (1 << 1), 140 /** 141 * If set, libgit2 was built with and linked against libssh2. A custom 142 * transport may still be added by the user to support libssh2 regardless of 143 * this. 144 */ 145 GIT_FEATURE_SSH = (1 << 2), 146 /** 147 * If set, libgit2 was built with support for sub-second resolution in file 148 * modification times. 149 */ 150 GIT_FEATURE_NSEC = (1 << 3), 151 } git_feature_t; 152 153 /** 154 * Query compile time options for libgit2. 155 * 156 * @return A combination of GIT_FEATURE_* values. 157 * 158 * - GIT_FEATURE_THREADS 159 * Libgit2 was compiled with thread support. Note that thread support is 160 * still to be seen as a 'work in progress' - basic object lookups are 161 * believed to be threadsafe, but other operations may not be. 162 * 163 * - GIT_FEATURE_HTTPS 164 * Libgit2 supports the https:// protocol. This requires the openssl 165 * library to be found when compiling libgit2. 166 * 167 * - GIT_FEATURE_SSH 168 * Libgit2 supports the SSH protocol for network operations. This requires 169 * the libssh2 library to be found when compiling libgit2 170 */ 171 GIT_EXTERN(int) git_libgit2_features(void); 172 173 /** 174 * Global library options 175 * 176 * These are used to select which global option to set or get and are 177 * used in `git_libgit2_opts()`. 178 */ 179 typedef enum { 180 GIT_OPT_GET_MWINDOW_SIZE, 181 GIT_OPT_SET_MWINDOW_SIZE, 182 GIT_OPT_GET_MWINDOW_MAPPED_LIMIT, 183 GIT_OPT_SET_MWINDOW_MAPPED_LIMIT, 184 GIT_OPT_GET_SEARCH_PATH, 185 GIT_OPT_SET_SEARCH_PATH, 186 GIT_OPT_SET_CACHE_OBJECT_LIMIT, 187 GIT_OPT_SET_CACHE_MAX_SIZE, 188 GIT_OPT_ENABLE_CACHING, 189 GIT_OPT_GET_CACHED_MEMORY, 190 GIT_OPT_GET_TEMPLATE_PATH, 191 GIT_OPT_SET_TEMPLATE_PATH, 192 GIT_OPT_SET_SSL_CERT_LOCATIONS, 193 GIT_OPT_SET_USER_AGENT, 194 GIT_OPT_ENABLE_STRICT_OBJECT_CREATION, 195 GIT_OPT_ENABLE_STRICT_SYMBOLIC_REF_CREATION, 196 GIT_OPT_SET_SSL_CIPHERS, 197 GIT_OPT_GET_USER_AGENT, 198 GIT_OPT_ENABLE_OFS_DELTA, 199 GIT_OPT_ENABLE_FSYNC_GITDIR, 200 GIT_OPT_GET_WINDOWS_SHAREMODE, 201 GIT_OPT_SET_WINDOWS_SHAREMODE, 202 GIT_OPT_ENABLE_STRICT_HASH_VERIFICATION, 203 GIT_OPT_SET_ALLOCATOR, 204 GIT_OPT_ENABLE_UNSAVED_INDEX_SAFETY, 205 GIT_OPT_GET_PACK_MAX_OBJECTS, 206 GIT_OPT_SET_PACK_MAX_OBJECTS, 207 GIT_OPT_DISABLE_PACK_KEEP_FILE_CHECKS, 208 GIT_OPT_ENABLE_HTTP_EXPECT_CONTINUE, 209 GIT_OPT_GET_MWINDOW_FILE_LIMIT, 210 GIT_OPT_SET_MWINDOW_FILE_LIMIT, 211 GIT_OPT_SET_ODB_PACKED_PRIORITY, 212 GIT_OPT_SET_ODB_LOOSE_PRIORITY 213 } git_libgit2_opt_t; 214 215 /** 216 * Set or query a library global option 217 * 218 * Available options: 219 * 220 * * opts(GIT_OPT_GET_MWINDOW_SIZE, size_t *): 221 * 222 * > Get the maximum mmap window size 223 * 224 * * opts(GIT_OPT_SET_MWINDOW_SIZE, size_t): 225 * 226 * > Set the maximum mmap window size 227 * 228 * * opts(GIT_OPT_GET_MWINDOW_MAPPED_LIMIT, size_t *): 229 * 230 * > Get the maximum memory that will be mapped in total by the library 231 * 232 * * opts(GIT_OPT_SET_MWINDOW_MAPPED_LIMIT, size_t): 233 * 234 * > Set the maximum amount of memory that can be mapped at any time 235 * > by the library 236 * 237 * * opts(GIT_OPT_GET_MWINDOW_FILE_LIMIT, size_t *): 238 * 239 * > Get the maximum number of files that will be mapped at any time by the 240 * > library 241 * 242 * * opts(GIT_OPT_SET_MWINDOW_FILE_LIMIT, size_t): 243 * 244 * > Set the maximum number of files that can be mapped at any time 245 * > by the library. The default (0) is unlimited. 246 * 247 * * opts(GIT_OPT_GET_SEARCH_PATH, int level, git_buf *buf) 248 * 249 * > Get the search path for a given level of config data. "level" must 250 * > be one of `GIT_CONFIG_LEVEL_SYSTEM`, `GIT_CONFIG_LEVEL_GLOBAL`, 251 * > `GIT_CONFIG_LEVEL_XDG`, or `GIT_CONFIG_LEVEL_PROGRAMDATA`. 252 * > The search path is written to the `out` buffer. 253 * 254 * * opts(GIT_OPT_SET_SEARCH_PATH, int level, const char *path) 255 * 256 * > Set the search path for a level of config data. The search path 257 * > applied to shared attributes and ignore files, too. 258 * > 259 * > - `path` lists directories delimited by GIT_PATH_LIST_SEPARATOR. 260 * > Pass NULL to reset to the default (generally based on environment 261 * > variables). Use magic path `$PATH` to include the old value 262 * > of the path (if you want to prepend or append, for instance). 263 * > 264 * > - `level` must be `GIT_CONFIG_LEVEL_SYSTEM`, 265 * > `GIT_CONFIG_LEVEL_GLOBAL`, `GIT_CONFIG_LEVEL_XDG`, or 266 * > `GIT_CONFIG_LEVEL_PROGRAMDATA`. 267 * 268 * * opts(GIT_OPT_SET_CACHE_OBJECT_LIMIT, git_object_t type, size_t size) 269 * 270 * > Set the maximum data size for the given type of object to be 271 * > considered eligible for caching in memory. Setting to value to 272 * > zero means that that type of object will not be cached. 273 * > Defaults to 0 for GIT_OBJECT_BLOB (i.e. won't cache blobs) and 4k 274 * > for GIT_OBJECT_COMMIT, GIT_OBJECT_TREE, and GIT_OBJECT_TAG. 275 * 276 * * opts(GIT_OPT_SET_CACHE_MAX_SIZE, ssize_t max_storage_bytes) 277 * 278 * > Set the maximum total data size that will be cached in memory 279 * > across all repositories before libgit2 starts evicting objects 280 * > from the cache. This is a soft limit, in that the library might 281 * > briefly exceed it, but will start aggressively evicting objects 282 * > from cache when that happens. The default cache size is 256MB. 283 * 284 * * opts(GIT_OPT_ENABLE_CACHING, int enabled) 285 * 286 * > Enable or disable caching completely. 287 * > 288 * > Because caches are repository-specific, disabling the cache 289 * > cannot immediately clear all cached objects, but each cache will 290 * > be cleared on the next attempt to update anything in it. 291 * 292 * * opts(GIT_OPT_GET_CACHED_MEMORY, ssize_t *current, ssize_t *allowed) 293 * 294 * > Get the current bytes in cache and the maximum that would be 295 * > allowed in the cache. 296 * 297 * * opts(GIT_OPT_GET_TEMPLATE_PATH, git_buf *out) 298 * 299 * > Get the default template path. 300 * > The path is written to the `out` buffer. 301 * 302 * * opts(GIT_OPT_SET_TEMPLATE_PATH, const char *path) 303 * 304 * > Set the default template path. 305 * > 306 * > - `path` directory of template. 307 * 308 * * opts(GIT_OPT_SET_SSL_CERT_LOCATIONS, const char *file, const char *path) 309 * 310 * > Set the SSL certificate-authority locations. 311 * > 312 * > - `file` is the location of a file containing several 313 * > certificates concatenated together. 314 * > - `path` is the location of a directory holding several 315 * > certificates, one per file. 316 * > 317 * > Either parameter may be `NULL`, but not both. 318 * 319 * * opts(GIT_OPT_SET_USER_AGENT, const char *user_agent) 320 * 321 * > Set the value of the User-Agent header. This value will be 322 * > appended to "git/1.0", for compatibility with other git clients. 323 * > 324 * > - `user_agent` is the value that will be delivered as the 325 * > User-Agent header on HTTP requests. 326 * 327 * * opts(GIT_OPT_SET_WINDOWS_SHAREMODE, unsigned long value) 328 * 329 * > Set the share mode used when opening files on Windows. 330 * > For more information, see the documentation for CreateFile. 331 * > The default is: FILE_SHARE_READ | FILE_SHARE_WRITE. This is 332 * > ignored and unused on non-Windows platforms. 333 * 334 * * opts(GIT_OPT_GET_WINDOWS_SHAREMODE, unsigned long *value) 335 * 336 * > Get the share mode used when opening files on Windows. 337 * 338 * * opts(GIT_OPT_ENABLE_STRICT_OBJECT_CREATION, int enabled) 339 * 340 * > Enable strict input validation when creating new objects 341 * > to ensure that all inputs to the new objects are valid. For 342 * > example, when this is enabled, the parent(s) and tree inputs 343 * > will be validated when creating a new commit. This defaults 344 * > to enabled. 345 * 346 * * opts(GIT_OPT_ENABLE_STRICT_SYMBOLIC_REF_CREATION, int enabled) 347 * 348 * > Validate the target of a symbolic ref when creating it. For 349 * > example, `foobar` is not a valid ref, therefore `foobar` is 350 * > not a valid target for a symbolic ref by default, whereas 351 * > `refs/heads/foobar` is. Disabling this bypasses validation 352 * > so that an arbitrary strings such as `foobar` can be used 353 * > for a symbolic ref target. This defaults to enabled. 354 * 355 * * opts(GIT_OPT_SET_SSL_CIPHERS, const char *ciphers) 356 * 357 * > Set the SSL ciphers use for HTTPS connections. 358 * > 359 * > - `ciphers` is the list of ciphers that are eanbled. 360 * 361 * * opts(GIT_OPT_GET_USER_AGENT, git_buf *out) 362 * 363 * > Get the value of the User-Agent header. 364 * > The User-Agent is written to the `out` buffer. 365 * 366 * * opts(GIT_OPT_ENABLE_OFS_DELTA, int enabled) 367 * 368 * > Enable or disable the use of "offset deltas" when creating packfiles, 369 * > and the negotiation of them when talking to a remote server. 370 * > Offset deltas store a delta base location as an offset into the 371 * > packfile from the current location, which provides a shorter encoding 372 * > and thus smaller resultant packfiles. 373 * > Packfiles containing offset deltas can still be read. 374 * > This defaults to enabled. 375 * 376 * * opts(GIT_OPT_ENABLE_FSYNC_GITDIR, int enabled) 377 * 378 * > Enable synchronized writes of files in the gitdir using `fsync` 379 * > (or the platform equivalent) to ensure that new object data 380 * > is written to permanent storage, not simply cached. This 381 * > defaults to disabled. 382 * 383 * opts(GIT_OPT_ENABLE_STRICT_HASH_VERIFICATION, int enabled) 384 * 385 * > Enable strict verification of object hashsums when reading 386 * > objects from disk. This may impact performance due to an 387 * > additional checksum calculation on each object. This defaults 388 * > to enabled. 389 * 390 * opts(GIT_OPT_SET_ALLOCATOR, git_allocator *allocator) 391 * 392 * > Set the memory allocator to a different memory allocator. This 393 * > allocator will then be used to make all memory allocations for 394 * > libgit2 operations. If the given `allocator` is NULL, then the 395 * > system default will be restored. 396 * 397 * opts(GIT_OPT_ENABLE_UNSAVED_INDEX_SAFETY, int enabled) 398 * 399 * > Ensure that there are no unsaved changes in the index before 400 * > beginning any operation that reloads the index from disk (eg, 401 * > checkout). If there are unsaved changes, the instruction will 402 * > fail. (Using the FORCE flag to checkout will still overwrite 403 * > these changes.) 404 * 405 * opts(GIT_OPT_GET_PACK_MAX_OBJECTS, size_t *out) 406 * 407 * > Get the maximum number of objects libgit2 will allow in a pack 408 * > file when downloading a pack file from a remote. This can be 409 * > used to limit maximum memory usage when fetching from an untrusted 410 * > remote. 411 * 412 * opts(GIT_OPT_SET_PACK_MAX_OBJECTS, size_t objects) 413 * 414 * > Set the maximum number of objects libgit2 will allow in a pack 415 * > file when downloading a pack file from a remote. 416 * 417 * opts(GIT_OPT_DISABLE_PACK_KEEP_FILE_CHECKS, int enabled) 418 * > This will cause .keep file existence checks to be skipped when 419 * > accessing packfiles, which can help performance with remote filesystems. 420 * 421 * opts(GIT_OPT_ENABLE_HTTP_EXPECT_CONTINUE, int enabled) 422 * > When connecting to a server using NTLM or Negotiate 423 * > authentication, use expect/continue when POSTing data. 424 * > This option is not available on Windows. 425 * 426 * opts(GIT_OPT_SET_ODB_PACKED_PRIORITY, int priority) 427 * > Override the default priority of the packed ODB backend which 428 * > is added when default backends are assigned to a repository 429 * 430 * opts(GIT_OPT_SET_ODB_LOOSE_PRIORITY, int priority) 431 * > Override the default priority of the loose ODB backend which 432 * > is added when default backends are assigned to a repository 433 * 434 * @param option Option key 435 * @param ... value to set the option 436 * @return 0 on success, <0 on failure 437 */ 438 GIT_EXTERN(int) git_libgit2_opts(int option, ...); 439 440 /** @} */ 441 GIT_END_DECL 442 443 #endif 444