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 /** This check is needed for importing this file in an iOS/OS X framework throws an error in Xcode otherwise.*/
  28 #elif !defined(__CLANG_INTTYPES_H)
  29 # include <inttypes.h>
  30 #endif
  31
  32 #ifdef DOCURIUM
  33 /*
  34  * This is so clang's doc parser acknowledges comments on functions
  35  * with size_t parameters.
  36  */
  37 typedef size_t size_t;
  38 #endif
  39
  40 /** Declare a public function exported for application use. */
  41 #if __GNUC__ >= 4
  42 # define GIT_EXTERN(type) extern \
  43                          __attribute__((visibility("default"))) \
  44                          type
  45 #elif defined(_MSC_VER)
  46 # define GIT_EXTERN(type) __declspec(dllexport) type
  47 #else
  48 # define GIT_EXTERN(type) extern type
  49 #endif
  50
  51 /** Declare a function's takes printf style arguments. */
  52 #ifdef __GNUC__
  53 # define GIT_FORMAT_PRINTF(a,b) __attribute__((format (printf, a, b)))
  54 #else
  55 # define GIT_FORMAT_PRINTF(a,b) /* empty */
  56 #endif
  57
  58 #if (defined(_WIN32)) && !defined(__CYGWIN__)
  59 #define GIT_WIN32 1
  60 #endif
  61
  62 #ifdef __amigaos4__
  63 #include <netinet/in.h>
  64 #endif
  65
  66 /**
  67  * @file git2/common.h
  68  * @brief Git common platform definitions
  69  * @defgroup git_common Git common platform definitions
  70  * @ingroup Git
  71  * @{
  72  */
  73
  74 GIT_BEGIN_DECL
  75
  76 /**
  77  * The separator used in path list strings (ie like in the PATH
  78  * environment variable). A semi-colon ";" is used on Windows, and
  79  * a colon ":" for all other systems.
  80  */
  81 #ifdef GIT_WIN32
  82 #define GIT_PATH_LIST_SEPARATOR ';'
  83 #else
  84 #define GIT_PATH_LIST_SEPARATOR ':'
  85 #endif
  86
  87 /**
  88  * The maximum length of a valid git path.
  89  */
  90 #define GIT_PATH_MAX 4096
  91
  92 /**
  93  * The string representation of the null object ID.
  94  */
  95 #define GIT_OID_HEX_ZERO "0000000000000000000000000000000000000000"
  96
  97 /**
  98  * Return the version of the libgit2 library
  99  * being currently used.
 100  *
 101  * @param major Store the major version number
 102  * @param minor Store the minor version number
 103  * @param rev Store the revision (patch) number
 104  */
 105 GIT_EXTERN(void) git_libgit2_version(int *major, int *minor, int *rev);
 106
 107 /**
 108  * Combinations of these values describe the features with which libgit2
 109  * was compiled
 110  */
 111 typedef enum {
 112   /**
 113    * If set, libgit2 was built thread-aware and can be safely used from multiple
 114    * threads.
 115    */
 116         GIT_FEATURE_THREADS     = (1 << 0),
 117   /**
 118    * If set, libgit2 was built with and linked against a TLS implementation.
 119    * Custom TLS streams may still be added by the user to support HTTPS
 120    * regardless of this.
 121    */
 122         GIT_FEATURE_HTTPS       = (1 << 1),
 123   /**
 124    * If set, libgit2 was built with and linked against libssh2. A custom
 125    * transport may still be added by the user to support libssh2 regardless of
 126    * this.
 127    */
 128         GIT_FEATURE_SSH         = (1 << 2),
 129   /**
 130    * If set, libgit2 was built with support for sub-second resolution in file
 131    * modification times.
 132    */
 133         GIT_FEATURE_NSEC        = (1 << 3),
 134 } git_feature_t;
 135
 136 /**
 137  * Query compile time options for libgit2.
 138  *
 139  * @return A combination of GIT_FEATURE_* values.
 140  *
 141  * - GIT_FEATURE_THREADS
 142  *   Libgit2 was compiled with thread support. Note that thread support is
 143  *   still to be seen as a 'work in progress' - basic object lookups are
 144  *   believed to be threadsafe, but other operations may not be.
 145  *
 146  * - GIT_FEATURE_HTTPS
 147  *   Libgit2 supports the https:// protocol. This requires the openssl
 148  *   library to be found when compiling libgit2.
 149  *
 150  * - GIT_FEATURE_SSH
 151  *   Libgit2 supports the SSH protocol for network operations. This requires
 152  *   the libssh2 library to be found when compiling libgit2
 153  */
 154 GIT_EXTERN(int) git_libgit2_features(void);
 155
 156 /**
 157  * Global library options
 158  *
 159  * These are used to select which global option to set or get and are
 160  * used in `git_libgit2_opts()`.
 161  */
 162 typedef enum {
 163         GIT_OPT_GET_MWINDOW_SIZE,
 164         GIT_OPT_SET_MWINDOW_SIZE,
 165         GIT_OPT_GET_MWINDOW_MAPPED_LIMIT,
 166         GIT_OPT_SET_MWINDOW_MAPPED_LIMIT,
 167         GIT_OPT_GET_SEARCH_PATH,
 168         GIT_OPT_SET_SEARCH_PATH,
 169         GIT_OPT_SET_CACHE_OBJECT_LIMIT,
 170         GIT_OPT_SET_CACHE_MAX_SIZE,
 171         GIT_OPT_ENABLE_CACHING,
 172         GIT_OPT_GET_CACHED_MEMORY,
 173         GIT_OPT_GET_TEMPLATE_PATH,
 174         GIT_OPT_SET_TEMPLATE_PATH,
 175         GIT_OPT_SET_SSL_CERT_LOCATIONS,
 176         GIT_OPT_SET_USER_AGENT,
 177         GIT_OPT_ENABLE_STRICT_OBJECT_CREATION,
 178         GIT_OPT_ENABLE_STRICT_SYMBOLIC_REF_CREATION,
 179         GIT_OPT_SET_SSL_CIPHERS,
 180         GIT_OPT_GET_USER_AGENT,
 181         GIT_OPT_ENABLE_OFS_DELTA,
 182         GIT_OPT_ENABLE_SYNCHRONOUS_OBJECT_CREATION,
 183         GIT_OPT_GET_WINDOWS_SHAREMODE,
 184         GIT_OPT_SET_WINDOWS_SHAREMODE,
 185 } git_libgit2_opt_t;
 186
 187 /**
 188  * Set or query a library global option
 189  *
 190  * Available options:
 191  *
 192  *      * opts(GIT_OPT_GET_MWINDOW_SIZE, size_t *):
 193  *
 194  *              > Get the maximum mmap window size
 195  *
 196  *      * opts(GIT_OPT_SET_MWINDOW_SIZE, size_t):
 197  *
 198  *              > Set the maximum mmap window size
 199  *
 200  *      * opts(GIT_OPT_GET_MWINDOW_MAPPED_LIMIT, size_t *):
 201  *
 202  *              > Get the maximum memory that will be mapped in total by the library
 203  *
 204  *      * opts(GIT_OPT_SET_MWINDOW_MAPPED_LIMIT, size_t):
 205  *
 206  *              >Set the maximum amount of memory that can be mapped at any time
 207  *              by the library
 208  *
 209  *      * opts(GIT_OPT_GET_SEARCH_PATH, int level, git_buf *buf)
 210  *
 211  *              > Get the search path for a given level of config data.  "level" must
 212  *              > be one of `GIT_CONFIG_LEVEL_SYSTEM`, `GIT_CONFIG_LEVEL_GLOBAL`,
 213  *              > `GIT_CONFIG_LEVEL_XDG`, or `GIT_CONFIG_LEVEL_PROGRAMDATA`.
 214  *              > The search path is written to the `out` buffer.
 215  *
 216  *      * opts(GIT_OPT_SET_SEARCH_PATH, int level, const char *path)
 217  *
 218  *              > Set the search path for a level of config data.  The search path
 219  *              > applied to shared attributes and ignore files, too.
 220  *              >
 221  *              > - `path` lists directories delimited by GIT_PATH_LIST_SEPARATOR.
 222  *              >   Pass NULL to reset to the default (generally based on environment
 223  *              >   variables).  Use magic path `$PATH` to include the old value
 224  *              >   of the path (if you want to prepend or append, for instance).
 225  *              >
 226  *              > - `level` must be `GIT_CONFIG_LEVEL_SYSTEM`,
 227  *              >   `GIT_CONFIG_LEVEL_GLOBAL`, `GIT_CONFIG_LEVEL_XDG`, or
 228  *              >   `GIT_CONFIG_LEVEL_PROGRAMDATA`.
 229  *
 230  *      * opts(GIT_OPT_SET_CACHE_OBJECT_LIMIT, git_otype type, size_t size)
 231  *
 232  *              > Set the maximum data size for the given type of object to be
 233  *              > considered eligible for caching in memory.  Setting to value to
 234  *              > zero means that that type of object will not be cached.
 235  *              > Defaults to 0 for GIT_OBJ_BLOB (i.e. won't cache blobs) and 4k
 236  *              > for GIT_OBJ_COMMIT, GIT_OBJ_TREE, and GIT_OBJ_TAG.
 237  *
 238  *      * opts(GIT_OPT_SET_CACHE_MAX_SIZE, ssize_t max_storage_bytes)
 239  *
 240  *              > Set the maximum total data size that will be cached in memory
 241  *              > across all repositories before libgit2 starts evicting objects
 242  *              > from the cache.  This is a soft limit, in that the library might
 243  *              > briefly exceed it, but will start aggressively evicting objects
 244  *              > from cache when that happens.  The default cache size is 256MB.
 245  *
 246  *      * opts(GIT_OPT_ENABLE_CACHING, int enabled)
 247  *
 248  *              > Enable or disable caching completely.
 249  *              >
 250  *              > Because caches are repository-specific, disabling the cache
 251  *              > cannot immediately clear all cached objects, but each cache will
 252  *              > be cleared on the next attempt to update anything in it.
 253  *
 254  *      * opts(GIT_OPT_GET_CACHED_MEMORY, ssize_t *current, ssize_t *allowed)
 255  *
 256  *              > Get the current bytes in cache and the maximum that would be
 257  *              > allowed in the cache.
 258  *
 259  *      * opts(GIT_OPT_GET_TEMPLATE_PATH, git_buf *out)
 260  *
 261  *              > Get the default template path.
 262  *              > The path is written to the `out` buffer.
 263  *
 264  *      * opts(GIT_OPT_SET_TEMPLATE_PATH, const char *path)
 265  *
 266  *              > Set the default template path.
 267  *              >
 268  *              > - `path` directory of template.
 269  *
 270  *      * opts(GIT_OPT_SET_SSL_CERT_LOCATIONS, const char *file, const char *path)
 271  *
 272  *              > Set the SSL certificate-authority locations.
 273  *              >
 274  *              > - `file` is the location of a file containing several
 275  *              >   certificates concatenated together.
 276  *              > - `path` is the location of a directory holding several
 277  *              >   certificates, one per file.
 278  *              >
 279  *              > Either parameter may be `NULL`, but not both.
 280  *
 281  *      * opts(GIT_OPT_SET_USER_AGENT, const char *user_agent)
 282  *
 283  *              > Set the value of the User-Agent header.  This value will be
 284  *              > appended to "git/1.0", for compatibility with other git clients.
 285  *              >
 286  *              > - `user_agent` is the value that will be delivered as the
 287  *              >   User-Agent header on HTTP requests.
 288  *
 289  *      * opts(GIT_OPT_SET_WINDOWS_SHAREMODE, unsigned long value)
 290  *
 291  *              > Set the share mode used when opening files on Windows.
 292  *              > For more information, see the documentation for CreateFile.
 293  *              > The default is: FILE_SHARE_READ | FILE_SHARE_WRITE.  This is
 294  *              > ignored and unused on non-Windows platforms.
 295  *
 296  *      * opts(GIT_OPT_GET_WINDOWS_SHAREMODE, unsigned long *value)
 297  *
 298  *              > Get the share mode used when opening files on Windows.
 299  *
 300  *      * opts(GIT_OPT_ENABLE_STRICT_OBJECT_CREATION, int enabled)
 301  *
 302  *              > Enable strict input validation when creating new objects
 303  *              > to ensure that all inputs to the new objects are valid.  For
 304  *              > example, when this is enabled, the parent(s) and tree inputs
 305  *              > will be validated when creating a new commit.  This defaults
 306  *              > to enabled.
 307  *
 308  *      * opts(GIT_OPT_ENABLE_STRICT_SYMBOLIC_REF_CREATION, int enabled)
 309  *
 310  *              > Validate the target of a symbolic ref when creating it.  For
 311  *              > example, `foobar` is not a valid ref, therefore `foobar` is
 312  *              > not a valid target for a symbolic ref by default, whereas
 313  *              > `refs/heads/foobar` is.  Disabling this bypasses validation
 314  *              > so that an arbitrary strings such as `foobar` can be used
 315  *              > for a symbolic ref target.  This defaults to enabled.
 316  *
 317  *      * opts(GIT_OPT_SET_SSL_CIPHERS, const char *ciphers)
 318  *
 319  *              > Set the SSL ciphers use for HTTPS connections.
 320  *              >
 321  *              > - `ciphers` is the list of ciphers that are eanbled.
 322  *
 323  *      * opts(GIT_OPT_ENABLE_OFS_DELTA, int enabled)
 324  *
 325  *              > Enable or disable the use of "offset deltas" when creating packfiles,
 326  *              > and the negotiation of them when talking to a remote server.
 327  *              > Offset deltas store a delta base location as an offset into the
 328  *              > packfile from the current location, which provides a shorter encoding
 329  *              > and thus smaller resultant packfiles.
 330  *              > Packfiles containing offset deltas can still be read.
 331  *              > This defaults to enabled.
 332  *
 333  *      * opts(GIT_OPT_ENABLE_SYNCHRONOUS_OBJECT_CREATION, int enabled)
 334  *
 335  *              > Enable synchronized writes of new objects using `fsync`
 336  *              > (or the platform equivalent) to ensure that new object data
 337  *              > is written to permanent storage, not simply cached.  This
 338  *              > defaults to disabled.
 339  *
 340  * @param option Option key
 341  * @param ... value to set the option
 342  * @return 0 on success, <0 on failure
 343  */
 344 GIT_EXTERN(int) git_libgit2_opts(int option, ...);
 345
 346 /** @} */
 347 GIT_END_DECL
 348
 349 #endif