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