include/git2/common.h

   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