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_OPT_GET_EXTENSIONS, 214 GIT_OPT_SET_EXTENSIONS 215 } git_libgit2_opt_t; 216 217 /** 218 * Set or query a library global option 219 * 220 * Available options: 221 * 222 * * opts(GIT_OPT_GET_MWINDOW_SIZE, size_t *): 223 * 224 * > Get the maximum mmap window size 225 * 226 * * opts(GIT_OPT_SET_MWINDOW_SIZE, size_t): 227 * 228 * > Set the maximum mmap window size 229 * 230 * * opts(GIT_OPT_GET_MWINDOW_MAPPED_LIMIT, size_t *): 231 * 232 * > Get the maximum memory that will be mapped in total by the library 233 * 234 * * opts(GIT_OPT_SET_MWINDOW_MAPPED_LIMIT, size_t): 235 * 236 * > Set the maximum amount of memory that can be mapped at any time 237 * > by the library 238 * 239 * * opts(GIT_OPT_GET_MWINDOW_FILE_LIMIT, size_t *): 240 * 241 * > Get the maximum number of files that will be mapped at any time by the 242 * > library 243 * 244 * * opts(GIT_OPT_SET_MWINDOW_FILE_LIMIT, size_t): 245 * 246 * > Set the maximum number of files that can be mapped at any time 247 * > by the library. The default (0) is unlimited. 248 * 249 * * opts(GIT_OPT_GET_SEARCH_PATH, int level, git_buf *buf) 250 * 251 * > Get the search path for a given level of config data. "level" must 252 * > be one of `GIT_CONFIG_LEVEL_SYSTEM`, `GIT_CONFIG_LEVEL_GLOBAL`, 253 * > `GIT_CONFIG_LEVEL_XDG`, or `GIT_CONFIG_LEVEL_PROGRAMDATA`. 254 * > The search path is written to the `out` buffer. 255 * 256 * * opts(GIT_OPT_SET_SEARCH_PATH, int level, const char *path) 257 * 258 * > Set the search path for a level of config data. The search path 259 * > applied to shared attributes and ignore files, too. 260 * > 261 * > - `path` lists directories delimited by GIT_PATH_LIST_SEPARATOR. 262 * > Pass NULL to reset to the default (generally based on environment 263 * > variables). Use magic path `$PATH` to include the old value 264 * > of the path (if you want to prepend or append, for instance). 265 * > 266 * > - `level` must be `GIT_CONFIG_LEVEL_SYSTEM`, 267 * > `GIT_CONFIG_LEVEL_GLOBAL`, `GIT_CONFIG_LEVEL_XDG`, or 268 * > `GIT_CONFIG_LEVEL_PROGRAMDATA`. 269 * 270 * * opts(GIT_OPT_SET_CACHE_OBJECT_LIMIT, git_object_t type, size_t size) 271 * 272 * > Set the maximum data size for the given type of object to be 273 * > considered eligible for caching in memory. Setting to value to 274 * > zero means that that type of object will not be cached. 275 * > Defaults to 0 for GIT_OBJECT_BLOB (i.e. won't cache blobs) and 4k 276 * > for GIT_OBJECT_COMMIT, GIT_OBJECT_TREE, and GIT_OBJECT_TAG. 277 * 278 * * opts(GIT_OPT_SET_CACHE_MAX_SIZE, ssize_t max_storage_bytes) 279 * 280 * > Set the maximum total data size that will be cached in memory 281 * > across all repositories before libgit2 starts evicting objects 282 * > from the cache. This is a soft limit, in that the library might 283 * > briefly exceed it, but will start aggressively evicting objects 284 * > from cache when that happens. The default cache size is 256MB. 285 * 286 * * opts(GIT_OPT_ENABLE_CACHING, int enabled) 287 * 288 * > Enable or disable caching completely. 289 * > 290 * > Because caches are repository-specific, disabling the cache 291 * > cannot immediately clear all cached objects, but each cache will 292 * > be cleared on the next attempt to update anything in it. 293 * 294 * * opts(GIT_OPT_GET_CACHED_MEMORY, ssize_t *current, ssize_t *allowed) 295 * 296 * > Get the current bytes in cache and the maximum that would be 297 * > allowed in the cache. 298 * 299 * * opts(GIT_OPT_GET_TEMPLATE_PATH, git_buf *out) 300 * 301 * > Get the default template path. 302 * > The path is written to the `out` buffer. 303 * 304 * * opts(GIT_OPT_SET_TEMPLATE_PATH, const char *path) 305 * 306 * > Set the default template path. 307 * > 308 * > - `path` directory of template. 309 * 310 * * opts(GIT_OPT_SET_SSL_CERT_LOCATIONS, const char *file, const char *path) 311 * 312 * > Set the SSL certificate-authority locations. 313 * > 314 * > - `file` is the location of a file containing several 315 * > certificates concatenated together. 316 * > - `path` is the location of a directory holding several 317 * > certificates, one per file. 318 * > 319 * > Either parameter may be `NULL`, but not both. 320 * 321 * * opts(GIT_OPT_SET_USER_AGENT, const char *user_agent) 322 * 323 * > Set the value of the User-Agent header. This value will be 324 * > appended to "git/1.0", for compatibility with other git clients. 325 * > 326 * > - `user_agent` is the value that will be delivered as the 327 * > User-Agent header on HTTP requests. 328 * 329 * * opts(GIT_OPT_SET_WINDOWS_SHAREMODE, unsigned long value) 330 * 331 * > Set the share mode used when opening files on Windows. 332 * > For more information, see the documentation for CreateFile. 333 * > The default is: FILE_SHARE_READ | FILE_SHARE_WRITE. This is 334 * > ignored and unused on non-Windows platforms. 335 * 336 * * opts(GIT_OPT_GET_WINDOWS_SHAREMODE, unsigned long *value) 337 * 338 * > Get the share mode used when opening files on Windows. 339 * 340 * * opts(GIT_OPT_ENABLE_STRICT_OBJECT_CREATION, int enabled) 341 * 342 * > Enable strict input validation when creating new objects 343 * > to ensure that all inputs to the new objects are valid. For 344 * > example, when this is enabled, the parent(s) and tree inputs 345 * > will be validated when creating a new commit. This defaults 346 * > to enabled. 347 * 348 * * opts(GIT_OPT_ENABLE_STRICT_SYMBOLIC_REF_CREATION, int enabled) 349 * 350 * > Validate the target of a symbolic ref when creating it. For 351 * > example, `foobar` is not a valid ref, therefore `foobar` is 352 * > not a valid target for a symbolic ref by default, whereas 353 * > `refs/heads/foobar` is. Disabling this bypasses validation 354 * > so that an arbitrary strings such as `foobar` can be used 355 * > for a symbolic ref target. This defaults to enabled. 356 * 357 * * opts(GIT_OPT_SET_SSL_CIPHERS, const char *ciphers) 358 * 359 * > Set the SSL ciphers use for HTTPS connections. 360 * > 361 * > - `ciphers` is the list of ciphers that are eanbled. 362 * 363 * * opts(GIT_OPT_GET_USER_AGENT, git_buf *out) 364 * 365 * > Get the value of the User-Agent header. 366 * > The User-Agent is written to the `out` buffer. 367 * 368 * * opts(GIT_OPT_ENABLE_OFS_DELTA, int enabled) 369 * 370 * > Enable or disable the use of "offset deltas" when creating packfiles, 371 * > and the negotiation of them when talking to a remote server. 372 * > Offset deltas store a delta base location as an offset into the 373 * > packfile from the current location, which provides a shorter encoding 374 * > and thus smaller resultant packfiles. 375 * > Packfiles containing offset deltas can still be read. 376 * > This defaults to enabled. 377 * 378 * * opts(GIT_OPT_ENABLE_FSYNC_GITDIR, int enabled) 379 * 380 * > Enable synchronized writes of files in the gitdir using `fsync` 381 * > (or the platform equivalent) to ensure that new object data 382 * > is written to permanent storage, not simply cached. This 383 * > defaults to disabled. 384 * 385 * opts(GIT_OPT_ENABLE_STRICT_HASH_VERIFICATION, int enabled) 386 * 387 * > Enable strict verification of object hashsums when reading 388 * > objects from disk. This may impact performance due to an 389 * > additional checksum calculation on each object. This defaults 390 * > to enabled. 391 * 392 * opts(GIT_OPT_SET_ALLOCATOR, git_allocator *allocator) 393 * 394 * > Set the memory allocator to a different memory allocator. This 395 * > allocator will then be used to make all memory allocations for 396 * > libgit2 operations. If the given `allocator` is NULL, then the 397 * > system default will be restored. 398 * 399 * opts(GIT_OPT_ENABLE_UNSAVED_INDEX_SAFETY, int enabled) 400 * 401 * > Ensure that there are no unsaved changes in the index before 402 * > beginning any operation that reloads the index from disk (eg, 403 * > checkout). If there are unsaved changes, the instruction will 404 * > fail. (Using the FORCE flag to checkout will still overwrite 405 * > these changes.) 406 * 407 * opts(GIT_OPT_GET_PACK_MAX_OBJECTS, size_t *out) 408 * 409 * > Get the maximum number of objects libgit2 will allow in a pack 410 * > file when downloading a pack file from a remote. This can be 411 * > used to limit maximum memory usage when fetching from an untrusted 412 * > remote. 413 * 414 * opts(GIT_OPT_SET_PACK_MAX_OBJECTS, size_t objects) 415 * 416 * > Set the maximum number of objects libgit2 will allow in a pack 417 * > file when downloading a pack file from a remote. 418 * 419 * opts(GIT_OPT_DISABLE_PACK_KEEP_FILE_CHECKS, int enabled) 420 * > This will cause .keep file existence checks to be skipped when 421 * > accessing packfiles, which can help performance with remote filesystems. 422 * 423 * opts(GIT_OPT_ENABLE_HTTP_EXPECT_CONTINUE, int enabled) 424 * > When connecting to a server using NTLM or Negotiate 425 * > authentication, use expect/continue when POSTing data. 426 * > This option is not available on Windows. 427 * 428 * opts(GIT_OPT_SET_ODB_PACKED_PRIORITY, int priority) 429 * > Override the default priority of the packed ODB backend which 430 * > is added when default backends are assigned to a repository 431 * 432 * opts(GIT_OPT_SET_ODB_LOOSE_PRIORITY, int priority) 433 * > Override the default priority of the loose ODB backend which 434 * > is added when default backends are assigned to a repository 435 * 436 * opts(GIT_OPT_GET_EXTENSIONS, git_strarray *out) 437 * > Returns the list of git extensions that are supported. This 438 * > is the list of built-in extensions supported by libgit2 and 439 * > custom extensions that have been added with 440 * > `GIT_OPT_SET_EXTENSIONS`. Extensions that have been negated 441 * > will not be returned. The returned list should be released 442 * > with `git_strarray_dispose`. 443 * 444 * opts(GIT_OPT_SET_EXTENSIONS, const char **extensions, size_t len) 445 * > Set that the given git extensions are supported by the caller. 446 * > Extensions supported by libgit2 may be negated by prefixing 447 * > them with a `!`. For example: setting extensions to 448 * > { "!noop", "newext" } indicates that the caller does not want 449 * > to support repositories with the `noop` extension but does want 450 * > to support repositories with the `newext` extension. 451 * 452 * @param option Option key 453 * @param ... value to set the option 454 * @return 0 on success, <0 on failure 455 */ 456 GIT_EXTERN(int) git_libgit2_opts(int option, ...); 457 458 /** @} */ 459 GIT_END_DECL 460 461 #endif 462