include/git2/common.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_git_common_h__
0008 #define INCLUDE_git_common_h__
0009
0010 #include <time.h>
0011 #include <stdlib.h>
0012
0013 #ifdef __cplusplus
0014 # define GIT_BEGIN_DECL extern "C" {
0015 # define GIT_END_DECL   }
0016 #else
0017  /** Start declarations in C mode */
0018 # define GIT_BEGIN_DECL /* empty */
0019  /** End declarations in C mode */
0020 # define GIT_END_DECL   /* empty */
0021 #endif
0022
0023 #if defined(_MSC_VER) && _MSC_VER < 1800
0024 # include <stdint.h>
0025 #elif !defined(__CLANG_INTTYPES_H)
0026 # include <inttypes.h>
0027 #endif
0028
0029 #ifdef DOCURIUM
0030 /*
0031  * This is so clang's doc parser acknowledges comments on functions
0032  * with size_t parameters.
0033  */
0034 typedef size_t size_t;
0035 #endif
0036
0037 /** Declare a public function exported for application use. */
0038 #if __GNUC__ >= 4
0039 # define GIT_EXTERN(type) extern \
0040              __attribute__((visibility("default"))) \
0041              type
0042 #elif defined(_MSC_VER)
0043 # define GIT_EXTERN(type) __declspec(dllexport) type __cdecl
0044 #else
0045 # define GIT_EXTERN(type) extern type
0046 #endif
0047
0048 /** Declare a callback function for application use. */
0049 #if defined(_MSC_VER)
0050 # define GIT_CALLBACK(name) (__cdecl *name)
0051 #else
0052 # define GIT_CALLBACK(name) (*name)
0053 #endif
0054
0055 /** Declare a function as deprecated. */
0056 #if defined(__GNUC__)
0057 # define GIT_DEPRECATED(func) \
0058              __attribute__((deprecated)) \
0059              __attribute__((used)) \
0060              func
0061 #elif defined(_MSC_VER)
0062 # define GIT_DEPRECATED(func) __declspec(deprecated) func
0063 #else
0064 # define GIT_DEPRECATED(func) func
0065 #endif
0066
0067 /** Declare a function's takes printf style arguments. */
0068 #ifdef __GNUC__
0069 # define GIT_FORMAT_PRINTF(a,b) __attribute__((format (printf, a, b)))
0070 #else
0071 # define GIT_FORMAT_PRINTF(a,b) /* empty */
0072 #endif
0073
0074 #if (defined(_WIN32)) && !defined(__CYGWIN__)
0075 #define GIT_WIN32 1
0076 #endif
0077
0078 #ifdef __amigaos4__
0079 #include <netinet/in.h>
0080 #endif
0081
0082 /**
0083  * @file git2/common.h
0084  * @brief Git common platform definitions
0085  * @defgroup git_common Git common platform definitions
0086  * @ingroup Git
0087  * @{
0088  */
0089
0090 GIT_BEGIN_DECL
0091
0092 /**
0093  * The separator used in path list strings (ie like in the PATH
0094  * environment variable). A semi-colon ";" is used on Windows and
0095  * AmigaOS, and a colon ":" for all other systems.
0096  */
0097 #if defined(GIT_WIN32) || defined(AMIGA)
0098 #define GIT_PATH_LIST_SEPARATOR ';'
0099 #else
0100 #define GIT_PATH_LIST_SEPARATOR ':'
0101 #endif
0102
0103 /**
0104  * The maximum length of a valid git path.
0105  */
0106 #define GIT_PATH_MAX 4096
0107
0108 /**
0109  * Return the version of the libgit2 library
0110  * being currently used.
0111  *
0112  * @param major Store the major version number
0113  * @param minor Store the minor version number
0114  * @param rev Store the revision (patch) number
0115  * @return 0 on success or an error code on failure
0116  */
0117 GIT_EXTERN(int) git_libgit2_version(int *major, int *minor, int *rev);
0118
0119 /**
0120  * Return the prerelease state of the libgit2 library currently being
0121  * used.  For nightly builds during active development, this will be
0122  * "alpha".  Releases may have a "beta" or release candidate ("rc1",
0123  * "rc2", etc) prerelease.  For a final release, this function returns
0124  * NULL.
0125  *
0126  * @return the name of the prerelease state or NULL
0127  */
0128 GIT_EXTERN(const char *) git_libgit2_prerelease(void);
0129
0130 /**
0131  * Combinations of these values describe the features with which libgit2
0132  * was compiled
0133  */
0134 typedef enum {
0135   /**
0136    * If set, libgit2 was built thread-aware and can be safely used from multiple
0137    * threads.
0138    */
0139     GIT_FEATURE_THREADS = (1 << 0),
0140   /**
0141    * If set, libgit2 was built with and linked against a TLS implementation.
0142    * Custom TLS streams may still be added by the user to support HTTPS
0143    * regardless of this.
0144    */
0145     GIT_FEATURE_HTTPS   = (1 << 1),
0146   /**
0147    * If set, libgit2 was built with and linked against libssh2. A custom
0148    * transport may still be added by the user to support libssh2 regardless of
0149    * this.
0150    */
0151     GIT_FEATURE_SSH     = (1 << 2),
0152   /**
0153    * If set, libgit2 was built with support for sub-second resolution in file
0154    * modification times.
0155    */
0156     GIT_FEATURE_NSEC    = (1 << 3)
0157 } git_feature_t;
0158
0159 /**
0160  * Query compile time options for libgit2.
0161  *
0162  * @return A combination of GIT_FEATURE_* values.
0163  *
0164  * - GIT_FEATURE_THREADS
0165  *   Libgit2 was compiled with thread support. Note that thread support is
0166  *   still to be seen as a 'work in progress' - basic object lookups are
0167  *   believed to be threadsafe, but other operations may not be.
0168  *
0169  * - GIT_FEATURE_HTTPS
0170  *   Libgit2 supports the https:// protocol. This requires the openssl
0171  *   library to be found when compiling libgit2.
0172  *
0173  * - GIT_FEATURE_SSH
0174  *   Libgit2 supports the SSH protocol for network operations. This requires
0175  *   the libssh2 library to be found when compiling libgit2
0176  *
0177  * - GIT_FEATURE_NSEC
0178  *   Libgit2 supports the sub-second resolution in file modification times.
0179  */
0180 GIT_EXTERN(int) git_libgit2_features(void);
0181
0182 /**
0183  * Global library options
0184  *
0185  * These are used to select which global option to set or get and are
0186  * used in `git_libgit2_opts()`.
0187  */
0188 typedef enum {
0189     GIT_OPT_GET_MWINDOW_SIZE,
0190     GIT_OPT_SET_MWINDOW_SIZE,
0191     GIT_OPT_GET_MWINDOW_MAPPED_LIMIT,
0192     GIT_OPT_SET_MWINDOW_MAPPED_LIMIT,
0193     GIT_OPT_GET_SEARCH_PATH,
0194     GIT_OPT_SET_SEARCH_PATH,
0195     GIT_OPT_SET_CACHE_OBJECT_LIMIT,
0196     GIT_OPT_SET_CACHE_MAX_SIZE,
0197     GIT_OPT_ENABLE_CACHING,
0198     GIT_OPT_GET_CACHED_MEMORY,
0199     GIT_OPT_GET_TEMPLATE_PATH,
0200     GIT_OPT_SET_TEMPLATE_PATH,
0201     GIT_OPT_SET_SSL_CERT_LOCATIONS,
0202     GIT_OPT_SET_USER_AGENT,
0203     GIT_OPT_ENABLE_STRICT_OBJECT_CREATION,
0204     GIT_OPT_ENABLE_STRICT_SYMBOLIC_REF_CREATION,
0205     GIT_OPT_SET_SSL_CIPHERS,
0206     GIT_OPT_GET_USER_AGENT,
0207     GIT_OPT_ENABLE_OFS_DELTA,
0208     GIT_OPT_ENABLE_FSYNC_GITDIR,
0209     GIT_OPT_GET_WINDOWS_SHAREMODE,
0210     GIT_OPT_SET_WINDOWS_SHAREMODE,
0211     GIT_OPT_ENABLE_STRICT_HASH_VERIFICATION,
0212     GIT_OPT_SET_ALLOCATOR,
0213     GIT_OPT_ENABLE_UNSAVED_INDEX_SAFETY,
0214     GIT_OPT_GET_PACK_MAX_OBJECTS,
0215     GIT_OPT_SET_PACK_MAX_OBJECTS,
0216     GIT_OPT_DISABLE_PACK_KEEP_FILE_CHECKS,
0217     GIT_OPT_ENABLE_HTTP_EXPECT_CONTINUE,
0218     GIT_OPT_GET_MWINDOW_FILE_LIMIT,
0219     GIT_OPT_SET_MWINDOW_FILE_LIMIT,
0220     GIT_OPT_SET_ODB_PACKED_PRIORITY,
0221     GIT_OPT_SET_ODB_LOOSE_PRIORITY,
0222     GIT_OPT_GET_EXTENSIONS,
0223     GIT_OPT_SET_EXTENSIONS,
0224     GIT_OPT_GET_OWNER_VALIDATION,
0225     GIT_OPT_SET_OWNER_VALIDATION,
0226     GIT_OPT_GET_HOMEDIR,
0227     GIT_OPT_SET_HOMEDIR,
0228     GIT_OPT_SET_SERVER_CONNECT_TIMEOUT,
0229     GIT_OPT_GET_SERVER_CONNECT_TIMEOUT,
0230     GIT_OPT_SET_SERVER_TIMEOUT,
0231     GIT_OPT_GET_SERVER_TIMEOUT
0232 } git_libgit2_opt_t;
0233
0234 /**
0235  * Set or query a library global option
0236  *
0237  * Available options:
0238  *
0239  *  * opts(GIT_OPT_GET_MWINDOW_SIZE, size_t *):
0240  *
0241  *      > Get the maximum mmap window size
0242  *
0243  *  * opts(GIT_OPT_SET_MWINDOW_SIZE, size_t):
0244  *
0245  *      > Set the maximum mmap window size
0246  *
0247  *  * opts(GIT_OPT_GET_MWINDOW_MAPPED_LIMIT, size_t *):
0248  *
0249  *      > Get the maximum memory that will be mapped in total by the library
0250  *
0251  *  * opts(GIT_OPT_SET_MWINDOW_MAPPED_LIMIT, size_t):
0252  *
0253  *      > Set the maximum amount of memory that can be mapped at any time
0254  *      > by the library
0255  *
0256  *  * opts(GIT_OPT_GET_MWINDOW_FILE_LIMIT, size_t *):
0257  *
0258  *      > Get the maximum number of files that will be mapped at any time by the
0259  *      > library
0260  *
0261  *  * opts(GIT_OPT_SET_MWINDOW_FILE_LIMIT, size_t):
0262  *
0263  *      > Set the maximum number of files that can be mapped at any time
0264  *      > by the library. The default (0) is unlimited.
0265  *
0266  *  * opts(GIT_OPT_GET_SEARCH_PATH, int level, git_buf *buf)
0267  *
0268  *      > Get the search path for a given level of config data.  "level" must
0269  *      > be one of `GIT_CONFIG_LEVEL_SYSTEM`, `GIT_CONFIG_LEVEL_GLOBAL`,
0270  *      > `GIT_CONFIG_LEVEL_XDG`, or `GIT_CONFIG_LEVEL_PROGRAMDATA`.
0271  *      > The search path is written to the `out` buffer.
0272  *
0273  *  * opts(GIT_OPT_SET_SEARCH_PATH, int level, const char *path)
0274  *
0275  *      > Set the search path for a level of config data.  The search path
0276  *      > applied to shared attributes and ignore files, too.
0277  *      >
0278  *      > - `path` lists directories delimited by GIT_PATH_LIST_SEPARATOR.
0279  *      >   Pass NULL to reset to the default (generally based on environment
0280  *      >   variables).  Use magic path `$PATH` to include the old value
0281  *      >   of the path (if you want to prepend or append, for instance).
0282  *      >
0283  *      > - `level` must be `GIT_CONFIG_LEVEL_SYSTEM`,
0284  *      >   `GIT_CONFIG_LEVEL_GLOBAL`, `GIT_CONFIG_LEVEL_XDG`, or
0285  *      >   `GIT_CONFIG_LEVEL_PROGRAMDATA`.
0286  *
0287  *  * opts(GIT_OPT_SET_CACHE_OBJECT_LIMIT, git_object_t type, size_t size)
0288  *
0289  *      > Set the maximum data size for the given type of object to be
0290  *      > considered eligible for caching in memory.  Setting to value to
0291  *      > zero means that that type of object will not be cached.
0292  *      > Defaults to 0 for GIT_OBJECT_BLOB (i.e. won't cache blobs) and 4k
0293  *      > for GIT_OBJECT_COMMIT, GIT_OBJECT_TREE, and GIT_OBJECT_TAG.
0294  *
0295  *  * opts(GIT_OPT_SET_CACHE_MAX_SIZE, ssize_t max_storage_bytes)
0296  *
0297  *      > Set the maximum total data size that will be cached in memory
0298  *      > across all repositories before libgit2 starts evicting objects
0299  *      > from the cache.  This is a soft limit, in that the library might
0300  *      > briefly exceed it, but will start aggressively evicting objects
0301  *      > from cache when that happens.  The default cache size is 256MB.
0302  *
0303  *  * opts(GIT_OPT_ENABLE_CACHING, int enabled)
0304  *
0305  *      > Enable or disable caching completely.
0306  *      >
0307  *      > Because caches are repository-specific, disabling the cache
0308  *      > cannot immediately clear all cached objects, but each cache will
0309  *      > be cleared on the next attempt to update anything in it.
0310  *
0311  *  * opts(GIT_OPT_GET_CACHED_MEMORY, ssize_t *current, ssize_t *allowed)
0312  *
0313  *      > Get the current bytes in cache and the maximum that would be
0314  *      > allowed in the cache.
0315  *
0316  *  * opts(GIT_OPT_GET_TEMPLATE_PATH, git_buf *out)
0317  *
0318  *      > Get the default template path.
0319  *      > The path is written to the `out` buffer.
0320  *
0321  *  * opts(GIT_OPT_SET_TEMPLATE_PATH, const char *path)
0322  *
0323  *      > Set the default template path.
0324  *      >
0325  *      > - `path` directory of template.
0326  *
0327  *  * opts(GIT_OPT_SET_SSL_CERT_LOCATIONS, const char *file, const char *path)
0328  *
0329  *      > Set the SSL certificate-authority locations.
0330  *      >
0331  *      > - `file` is the location of a file containing several
0332  *      >   certificates concatenated together.
0333  *      > - `path` is the location of a directory holding several
0334  *      >   certificates, one per file.
0335  *      >
0336  *      > Either parameter may be `NULL`, but not both.
0337  *
0338  *  * opts(GIT_OPT_SET_USER_AGENT, const char *user_agent)
0339  *
0340  *      > Set the value of the User-Agent header.  This value will be
0341  *      > appended to "git/1.0", for compatibility with other git clients.
0342  *      >
0343  *      > - `user_agent` is the value that will be delivered as the
0344  *      >   User-Agent header on HTTP requests.
0345  *
0346  *  * opts(GIT_OPT_SET_WINDOWS_SHAREMODE, unsigned long value)
0347  *
0348  *      > Set the share mode used when opening files on Windows.
0349  *      > For more information, see the documentation for CreateFile.
0350  *      > The default is: FILE_SHARE_READ | FILE_SHARE_WRITE.  This is
0351  *      > ignored and unused on non-Windows platforms.
0352  *
0353  *  * opts(GIT_OPT_GET_WINDOWS_SHAREMODE, unsigned long *value)
0354  *
0355  *      > Get the share mode used when opening files on Windows.
0356  *
0357  *  * opts(GIT_OPT_ENABLE_STRICT_OBJECT_CREATION, int enabled)
0358  *
0359  *      > Enable strict input validation when creating new objects
0360  *      > to ensure that all inputs to the new objects are valid.  For
0361  *      > example, when this is enabled, the parent(s) and tree inputs
0362  *      > will be validated when creating a new commit.  This defaults
0363  *      > to enabled.
0364  *
0365  *  * opts(GIT_OPT_ENABLE_STRICT_SYMBOLIC_REF_CREATION, int enabled)
0366  *
0367  *      > Validate the target of a symbolic ref when creating it.  For
0368  *      > example, `foobar` is not a valid ref, therefore `foobar` is
0369  *      > not a valid target for a symbolic ref by default, whereas
0370  *      > `refs/heads/foobar` is.  Disabling this bypasses validation
0371  *      > so that an arbitrary strings such as `foobar` can be used
0372  *      > for a symbolic ref target.  This defaults to enabled.
0373  *
0374  *  * opts(GIT_OPT_SET_SSL_CIPHERS, const char *ciphers)
0375  *
0376  *      > Set the SSL ciphers use for HTTPS connections.
0377  *      >
0378  *      > - `ciphers` is the list of ciphers that are eanbled.
0379  *
0380  *  * opts(GIT_OPT_GET_USER_AGENT, git_buf *out)
0381  *
0382  *      > Get the value of the User-Agent header.
0383  *      > The User-Agent is written to the `out` buffer.
0384  *
0385  *  * opts(GIT_OPT_ENABLE_OFS_DELTA, int enabled)
0386  *
0387  *      > Enable or disable the use of "offset deltas" when creating packfiles,
0388  *      > and the negotiation of them when talking to a remote server.
0389  *      > Offset deltas store a delta base location as an offset into the
0390  *      > packfile from the current location, which provides a shorter encoding
0391  *      > and thus smaller resultant packfiles.
0392  *      > Packfiles containing offset deltas can still be read.
0393  *      > This defaults to enabled.
0394  *
0395  *  * opts(GIT_OPT_ENABLE_FSYNC_GITDIR, int enabled)
0396  *
0397  *      > Enable synchronized writes of files in the gitdir using `fsync`
0398  *      > (or the platform equivalent) to ensure that new object data
0399  *      > is written to permanent storage, not simply cached.  This
0400  *      > defaults to disabled.
0401  *
0402  *   opts(GIT_OPT_ENABLE_STRICT_HASH_VERIFICATION, int enabled)
0403  *
0404  *      > Enable strict verification of object hashsums when reading
0405  *      > objects from disk. This may impact performance due to an
0406  *      > additional checksum calculation on each object. This defaults
0407  *      > to enabled.
0408  *
0409  *   opts(GIT_OPT_SET_ALLOCATOR, git_allocator *allocator)
0410  *
0411  *      > Set the memory allocator to a different memory allocator. This
0412  *      > allocator will then be used to make all memory allocations for
0413  *      > libgit2 operations.  If the given `allocator` is NULL, then the
0414  *      > system default will be restored.
0415  *
0416  *   opts(GIT_OPT_ENABLE_UNSAVED_INDEX_SAFETY, int enabled)
0417  *
0418  *      > Ensure that there are no unsaved changes in the index before
0419  *      > beginning any operation that reloads the index from disk (eg,
0420  *      > checkout).  If there are unsaved changes, the instruction will
0421  *      > fail.  (Using the FORCE flag to checkout will still overwrite
0422  *      > these changes.)
0423  *
0424  *   opts(GIT_OPT_GET_PACK_MAX_OBJECTS, size_t *out)
0425  *
0426  *      > Get the maximum number of objects libgit2 will allow in a pack
0427  *      > file when downloading a pack file from a remote. This can be
0428  *      > used to limit maximum memory usage when fetching from an untrusted
0429  *      > remote.
0430  *
0431  *   opts(GIT_OPT_SET_PACK_MAX_OBJECTS, size_t objects)
0432  *
0433  *      > Set the maximum number of objects libgit2 will allow in a pack
0434  *      > file when downloading a pack file from a remote.
0435  *
0436  *   opts(GIT_OPT_DISABLE_PACK_KEEP_FILE_CHECKS, int enabled)
0437  *      > This will cause .keep file existence checks to be skipped when
0438  *      > accessing packfiles, which can help performance with remote filesystems.
0439  *
0440  *   opts(GIT_OPT_ENABLE_HTTP_EXPECT_CONTINUE, int enabled)
0441  *      > When connecting to a server using NTLM or Negotiate
0442  *      > authentication, use expect/continue when POSTing data.
0443  *      > This option is not available on Windows.
0444  *
0445  *   opts(GIT_OPT_SET_ODB_PACKED_PRIORITY, int priority)
0446  *      > Override the default priority of the packed ODB backend which
0447  *      > is added when default backends are assigned to a repository
0448  *
0449  *   opts(GIT_OPT_SET_ODB_LOOSE_PRIORITY, int priority)
0450  *      > Override the default priority of the loose ODB backend which
0451  *      > is added when default backends are assigned to a repository
0452  *
0453  *   opts(GIT_OPT_GET_EXTENSIONS, git_strarray *out)
0454  *      > Returns the list of git extensions that are supported.  This
0455  *      > is the list of built-in extensions supported by libgit2 and
0456  *      > custom extensions that have been added with
0457  *      > `GIT_OPT_SET_EXTENSIONS`.  Extensions that have been negated
0458  *      > will not be returned.  The returned list should be released
0459  *      > with `git_strarray_dispose`.
0460  *
0461  *   opts(GIT_OPT_SET_EXTENSIONS, const char **extensions, size_t len)
0462  *      > Set that the given git extensions are supported by the caller.
0463  *      > Extensions supported by libgit2 may be negated by prefixing
0464  *      > them with a `!`.  For example: setting extensions to
0465  *      > { "!noop", "newext" } indicates that the caller does not want
0466  *      > to support repositories with the `noop` extension but does want
0467  *      > to support repositories with the `newext` extension.
0468  *
0469  *   opts(GIT_OPT_GET_OWNER_VALIDATION, int *enabled)
0470  *      > Gets the owner validation setting for repository
0471  *      > directories.
0472  *
0473  *   opts(GIT_OPT_SET_OWNER_VALIDATION, int enabled)
0474  *      > Set that repository directories should be owned by the current
0475  *      > user. The default is to validate ownership.
0476  *
0477  *   opts(GIT_OPT_GET_HOMEDIR, git_buf *out)
0478  *      > Gets the current user's home directory, as it will be used
0479  *      > for file lookups. The path is written to the `out` buffer.
0480  *
0481  *   opts(GIT_OPT_SET_HOMEDIR, const char *path)
0482  *      > Sets the directory used as the current user's home directory,
0483  *      > for file lookups.
0484  *      >
0485  *      > - `path` directory of home directory.
0486  *
0487  *   opts(GIT_OPT_GET_SERVER_CONNECT_TIMEOUT, int *timeout)
0488  *      > Gets the timeout (in milliseconds) to attempt connections to
0489  *      > a remote server.
0490  *
0491  *   opts(GIT_OPT_SET_SERVER_CONNECT_TIMEOUT, int timeout)
0492  *      > Sets the timeout (in milliseconds) to attempt connections to
0493  *      > a remote server. Set to 0 to use the system default. Note that
0494  *      > this may not be able to be configured longer than the system
0495  *      > default, typically 75 seconds.
0496  *
0497  *   opts(GIT_OPT_GET_SERVER_TIMEOUT, int *timeout)
0498  *      > Gets the timeout (in milliseconds) for reading from and writing
0499  *      > to a remote server.
0500  *
0501  *   opts(GIT_OPT_SET_SERVER_TIMEOUT, int timeout)
0502  *      > Sets the timeout (in milliseconds) for reading from and writing
0503  *      > to a remote server. Set to 0 to use the system default.
0504  *
0505  * @param option Option key
0506  * @param ... value to set the option
0507  * @return 0 on success, <0 on failure
0508  */
0509 GIT_EXTERN(int) git_libgit2_opts(int option, ...);
0510
0511 /** @} */
0512 GIT_END_DECL
0513
0514 #endif