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