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  GIT_BEGIN_DECL
  25 # include "inttypes.h"
  26  GIT_END_DECL
  27 #else
  28 # include <inttypes.h>
  29 #endif
  30
  31 /** Declare a public function exported for application use. */
  32 #if __GNUC__ >= 4
  33 # define GIT_EXTERN(type) extern \
  34                          __attribute__((visibility("default"))) \
  35                          type
  36 #elif defined(_MSC_VER)
  37 # define GIT_EXTERN(type) __declspec(dllexport) type
  38 #else
  39 # define GIT_EXTERN(type) extern type
  40 #endif
  41
  42 /** Declare a function's takes printf style arguments. */
  43 #ifdef __GNUC__
  44 # define GIT_FORMAT_PRINTF(a,b) __attribute__((format (printf, a, b)))
  45 #else
  46 # define GIT_FORMAT_PRINTF(a,b) /* empty */
  47 #endif
  48
  49 #if (defined(_WIN32)) && !defined(__CYGWIN__)
  50 #define GIT_WIN32 1
  51 #endif
  52
  53 #ifdef __amigaos4__
  54 #include <netinet/in.h>
  55 #endif
  56
  57 /**
  58  * @file git2/common.h
  59  * @brief Git common platform definitions
  60  * @defgroup git_common Git common platform definitions
  61  * @ingroup Git
  62  * @{
  63  */
  64
  65 GIT_BEGIN_DECL
  66
  67 /**
  68  * The separator used in path list strings (ie like in the PATH
  69  * environment variable). A semi-colon ";" is used on Windows, and
  70  * a colon ":" for all other systems.
  71  */
  72 #ifdef GIT_WIN32
  73 #define GIT_PATH_LIST_SEPARATOR ';'
  74 #else
  75 #define GIT_PATH_LIST_SEPARATOR ':'
  76 #endif
  77
  78 /**
  79  * The maximum length of a valid git path.
  80  */
  81 #define GIT_PATH_MAX 4096
  82
  83 /**
  84  * The string representation of the null object ID.
  85  */
  86 #define GIT_OID_HEX_ZERO "0000000000000000000000000000000000000000"
  87
  88 /**
  89  * Return the version of the libgit2 library
  90  * being currently used.
  91  *
  92  * @param major Store the major version number
  93  * @param minor Store the minor version number
  94  * @param rev Store the revision (patch) number
  95  */
  96 GIT_EXTERN(void) git_libgit2_version(int *major, int *minor, int *rev);
  97
  98 /**
  99  * Combinations of these values describe the features with which libgit2
 100  * was compiled
 101  */
 102 typedef enum {
 103         GIT_FEATURE_THREADS     = (1 << 0),
 104         GIT_FEATURE_HTTPS = (1 << 1),
 105         GIT_FEATURE_SSH = (1 << 2),
 106 } git_feature_t;
 107
 108 /**
 109  * Query compile time options for libgit2.
 110  *
 111  * @return A combination of GIT_FEATURE_* values.
 112  *
 113  * - GIT_FEATURE_THREADS
 114  *   Libgit2 was compiled with thread support. Note that thread support is
 115  *   still to be seen as a 'work in progress' - basic object lookups are
 116  *   believed to be threadsafe, but other operations may not be.
 117  *
 118  * - GIT_FEATURE_HTTPS
 119  *   Libgit2 supports the https:// protocol. This requires the openssl
 120  *   library to be found when compiling libgit2.
 121  *
 122  * - GIT_FEATURE_SSH
 123  *   Libgit2 supports the SSH protocol for network operations. This requires
 124  *   the libssh2 library to be found when compiling libgit2
 125  */
 126 GIT_EXTERN(int) git_libgit2_features(void);
 127
 128 /**
 129  * Global library options
 130  *
 131  * These are used to select which global option to set or get and are
 132  * used in `git_libgit2_opts()`.
 133  */
 134 typedef enum {
 135         GIT_OPT_GET_MWINDOW_SIZE,
 136         GIT_OPT_SET_MWINDOW_SIZE,
 137         GIT_OPT_GET_MWINDOW_MAPPED_LIMIT,
 138         GIT_OPT_SET_MWINDOW_MAPPED_LIMIT,
 139         GIT_OPT_GET_SEARCH_PATH,
 140         GIT_OPT_SET_SEARCH_PATH,
 141         GIT_OPT_SET_CACHE_OBJECT_LIMIT,
 142         GIT_OPT_SET_CACHE_MAX_SIZE,
 143         GIT_OPT_ENABLE_CACHING,
 144         GIT_OPT_GET_CACHED_MEMORY,
 145         GIT_OPT_GET_TEMPLATE_PATH,
 146         GIT_OPT_SET_TEMPLATE_PATH,
 147         GIT_OPT_SET_SSL_CERT_LOCATIONS,
 148 } git_libgit2_opt_t;
 149
 150 /**
 151  * Set or query a library global option
 152  *
 153  * Available options:
 154  *
 155  *      * opts(GIT_OPT_GET_MWINDOW_SIZE, size_t *):
 156  *
 157  *              > Get the maximum mmap window size
 158  *
 159  *      * opts(GIT_OPT_SET_MWINDOW_SIZE, size_t):
 160  *
 161  *              > Set the maximum mmap window size
 162  *
 163  *      * opts(GIT_OPT_GET_MWINDOW_MAPPED_LIMIT, size_t *):
 164  *
 165  *              > Get the maximum memory that will be mapped in total by the library
 166  *
 167  *      * opts(GIT_OPT_SET_MWINDOW_MAPPED_LIMIT, size_t):
 168  *
 169  *              >Set the maximum amount of memory that can be mapped at any time
 170  *              by the library
 171  *
 172  *      * opts(GIT_OPT_GET_SEARCH_PATH, int level, git_buf *buf)
 173  *
 174  *              > Get the search path for a given level of config data.  "level" must
 175  *              > be one of `GIT_CONFIG_LEVEL_SYSTEM`, `GIT_CONFIG_LEVEL_GLOBAL`, or
 176  *              > `GIT_CONFIG_LEVEL_XDG`.  The search path is written to the `out`
 177  *              > buffer.
 178  *
 179  *      * opts(GIT_OPT_SET_SEARCH_PATH, int level, const char *path)
 180  *
 181  *              > Set the search path for a level of config data.  The search path
 182  *              > applied to shared attributes and ignore files, too.
 183  *              >
 184  *              > - `path` lists directories delimited by GIT_PATH_LIST_SEPARATOR.
 185  *              >   Pass NULL to reset to the default (generally based on environment
 186  *              >   variables).  Use magic path `$PATH` to include the old value
 187  *              >   of the path (if you want to prepend or append, for instance).
 188  *              >
 189  *              > - `level` must be GIT_CONFIG_LEVEL_SYSTEM, GIT_CONFIG_LEVEL_GLOBAL,
 190  *              >   or GIT_CONFIG_LEVEL_XDG.
 191  *
 192  *      * opts(GIT_OPT_SET_CACHE_OBJECT_LIMIT, git_otype type, size_t size)
 193  *
 194  *              > Set the maximum data size for the given type of object to be
 195  *              > considered eligible for caching in memory.  Setting to value to
 196  *              > zero means that that type of object will not be cached.
 197  *              > Defaults to 0 for GIT_OBJ_BLOB (i.e. won't cache blobs) and 4k
 198  *              > for GIT_OBJ_COMMIT, GIT_OBJ_TREE, and GIT_OBJ_TAG.
 199  *
 200  *      * opts(GIT_OPT_SET_CACHE_MAX_SIZE, ssize_t max_storage_bytes)
 201  *
 202  *              > Set the maximum total data size that will be cached in memory
 203  *              > across all repositories before libgit2 starts evicting objects
 204  *              > from the cache.  This is a soft limit, in that the library might
 205  *              > briefly exceed it, but will start aggressively evicting objects
 206  *              > from cache when that happens.  The default cache size is 256MB.
 207  *
 208  *      * opts(GIT_OPT_ENABLE_CACHING, int enabled)
 209  *
 210  *              > Enable or disable caching completely.
 211  *              >
 212  *              > Because caches are repository-specific, disabling the cache
 213  *              > cannot immediately clear all cached objects, but each cache will
 214  *              > be cleared on the next attempt to update anything in it.
 215  *
 216  *      * opts(GIT_OPT_GET_CACHED_MEMORY, ssize_t *current, ssize_t *allowed)
 217  *
 218  *              > Get the current bytes in cache and the maximum that would be
 219  *              > allowed in the cache.
 220  *
 221  *      * opts(GIT_OPT_GET_TEMPLATE_PATH, git_buf *out)
 222  *
 223  *              > Get the default template path.
 224  *              > The path is written to the `out` buffer.
 225  *
 226  *      * opts(GIT_OPT_SET_TEMPLATE_PATH, const char *path)
 227  *
 228  *              > Set the default template path.
 229  *              >
 230  *              > - `path` directory of template.
 231  *
 232  *      * opts(GIT_OPT_SET_SSL_CERT_LOCATIONS, const char *file, const char *path)
 233  *
 234  *              > Set the SSL certificate-authority locations.
 235  *              >
 236  *              > - `file` is the location of a file containing several
 237  *              >   certificates concatenated together.
 238  *              > - `path` is the location of a directory holding several
 239  *              >   certificates, one per file.
 240  *              >
 241  *              > Either parameter may be `NULL`, but not both.
 242  *
 243  * @param option Option key
 244  * @param ... value to set the option
 245  * @return 0 on success, <0 on failure
 246  */
 247 GIT_EXTERN(int) git_libgit2_opts(int option, ...);
 248
 249 /** @} */
 250 GIT_END_DECL
 251
 252 #endif