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_FSYNC_GITDIR, 183 GIT_OPT_GET_WINDOWS_SHAREMODE, 184 GIT_OPT_SET_WINDOWS_SHAREMODE, 185 GIT_OPT_ENABLE_STRICT_HASH_VERIFICATION, 186 } git_libgit2_opt_t; 187 188 /** 189 * Set or query a library global option 190 * 191 * Available options: 192 * 193 * * opts(GIT_OPT_GET_MWINDOW_SIZE, size_t *): 194 * 195 * > Get the maximum mmap window size 196 * 197 * * opts(GIT_OPT_SET_MWINDOW_SIZE, size_t): 198 * 199 * > Set the maximum mmap window size 200 * 201 * * opts(GIT_OPT_GET_MWINDOW_MAPPED_LIMIT, size_t *): 202 * 203 * > Get the maximum memory that will be mapped in total by the library 204 * 205 * * opts(GIT_OPT_SET_MWINDOW_MAPPED_LIMIT, size_t): 206 * 207 * >Set the maximum amount of memory that can be mapped at any time 208 * by the library 209 * 210 * * opts(GIT_OPT_GET_SEARCH_PATH, int level, git_buf *buf) 211 * 212 * > Get the search path for a given level of config data. "level" must 213 * > be one of `GIT_CONFIG_LEVEL_SYSTEM`, `GIT_CONFIG_LEVEL_GLOBAL`, 214 * > `GIT_CONFIG_LEVEL_XDG`, or `GIT_CONFIG_LEVEL_PROGRAMDATA`. 215 * > The search path is written to the `out` buffer. 216 * 217 * * opts(GIT_OPT_SET_SEARCH_PATH, int level, const char *path) 218 * 219 * > Set the search path for a level of config data. The search path 220 * > applied to shared attributes and ignore files, too. 221 * > 222 * > - `path` lists directories delimited by GIT_PATH_LIST_SEPARATOR. 223 * > Pass NULL to reset to the default (generally based on environment 224 * > variables). Use magic path `$PATH` to include the old value 225 * > of the path (if you want to prepend or append, for instance). 226 * > 227 * > - `level` must be `GIT_CONFIG_LEVEL_SYSTEM`, 228 * > `GIT_CONFIG_LEVEL_GLOBAL`, `GIT_CONFIG_LEVEL_XDG`, or 229 * > `GIT_CONFIG_LEVEL_PROGRAMDATA`. 230 * 231 * * opts(GIT_OPT_SET_CACHE_OBJECT_LIMIT, git_otype type, size_t size) 232 * 233 * > Set the maximum data size for the given type of object to be 234 * > considered eligible for caching in memory. Setting to value to 235 * > zero means that that type of object will not be cached. 236 * > Defaults to 0 for GIT_OBJ_BLOB (i.e. won't cache blobs) and 4k 237 * > for GIT_OBJ_COMMIT, GIT_OBJ_TREE, and GIT_OBJ_TAG. 238 * 239 * * opts(GIT_OPT_SET_CACHE_MAX_SIZE, ssize_t max_storage_bytes) 240 * 241 * > Set the maximum total data size that will be cached in memory 242 * > across all repositories before libgit2 starts evicting objects 243 * > from the cache. This is a soft limit, in that the library might 244 * > briefly exceed it, but will start aggressively evicting objects 245 * > from cache when that happens. The default cache size is 256MB. 246 * 247 * * opts(GIT_OPT_ENABLE_CACHING, int enabled) 248 * 249 * > Enable or disable caching completely. 250 * > 251 * > Because caches are repository-specific, disabling the cache 252 * > cannot immediately clear all cached objects, but each cache will 253 * > be cleared on the next attempt to update anything in it. 254 * 255 * * opts(GIT_OPT_GET_CACHED_MEMORY, ssize_t *current, ssize_t *allowed) 256 * 257 * > Get the current bytes in cache and the maximum that would be 258 * > allowed in the cache. 259 * 260 * * opts(GIT_OPT_GET_TEMPLATE_PATH, git_buf *out) 261 * 262 * > Get the default template path. 263 * > The path is written to the `out` buffer. 264 * 265 * * opts(GIT_OPT_SET_TEMPLATE_PATH, const char *path) 266 * 267 * > Set the default template path. 268 * > 269 * > - `path` directory of template. 270 * 271 * * opts(GIT_OPT_SET_SSL_CERT_LOCATIONS, const char *file, const char *path) 272 * 273 * > Set the SSL certificate-authority locations. 274 * > 275 * > - `file` is the location of a file containing several 276 * > certificates concatenated together. 277 * > - `path` is the location of a directory holding several 278 * > certificates, one per file. 279 * > 280 * > Either parameter may be `NULL`, but not both. 281 * 282 * * opts(GIT_OPT_SET_USER_AGENT, const char *user_agent) 283 * 284 * > Set the value of the User-Agent header. This value will be 285 * > appended to "git/1.0", for compatibility with other git clients. 286 * > 287 * > - `user_agent` is the value that will be delivered as the 288 * > User-Agent header on HTTP requests. 289 * 290 * * opts(GIT_OPT_SET_WINDOWS_SHAREMODE, unsigned long value) 291 * 292 * > Set the share mode used when opening files on Windows. 293 * > For more information, see the documentation for CreateFile. 294 * > The default is: FILE_SHARE_READ | FILE_SHARE_WRITE. This is 295 * > ignored and unused on non-Windows platforms. 296 * 297 * * opts(GIT_OPT_GET_WINDOWS_SHAREMODE, unsigned long *value) 298 * 299 * > Get the share mode used when opening files on Windows. 300 * 301 * * opts(GIT_OPT_ENABLE_STRICT_OBJECT_CREATION, int enabled) 302 * 303 * > Enable strict input validation when creating new objects 304 * > to ensure that all inputs to the new objects are valid. For 305 * > example, when this is enabled, the parent(s) and tree inputs 306 * > will be validated when creating a new commit. This defaults 307 * > to enabled. 308 * 309 * * opts(GIT_OPT_ENABLE_STRICT_SYMBOLIC_REF_CREATION, int enabled) 310 * 311 * > Validate the target of a symbolic ref when creating it. For 312 * > example, `foobar` is not a valid ref, therefore `foobar` is 313 * > not a valid target for a symbolic ref by default, whereas 314 * > `refs/heads/foobar` is. Disabling this bypasses validation 315 * > so that an arbitrary strings such as `foobar` can be used 316 * > for a symbolic ref target. This defaults to enabled. 317 * 318 * * opts(GIT_OPT_SET_SSL_CIPHERS, const char *ciphers) 319 * 320 * > Set the SSL ciphers use for HTTPS connections. 321 * > 322 * > - `ciphers` is the list of ciphers that are eanbled. 323 * 324 * * opts(GIT_OPT_ENABLE_OFS_DELTA, int enabled) 325 * 326 * > Enable or disable the use of "offset deltas" when creating packfiles, 327 * > and the negotiation of them when talking to a remote server. 328 * > Offset deltas store a delta base location as an offset into the 329 * > packfile from the current location, which provides a shorter encoding 330 * > and thus smaller resultant packfiles. 331 * > Packfiles containing offset deltas can still be read. 332 * > This defaults to enabled. 333 * 334 * * opts(GIT_OPT_ENABLE_FSYNC_GITDIR, int enabled) 335 * 336 * > Enable synchronized writes of files in the gitdir using `fsync` 337 * > (or the platform equivalent) to ensure that new object data 338 * > is written to permanent storage, not simply cached. This 339 * > defaults to disabled. 340 * 341 * opts(GIT_OPT_ENABLE_STRICT_HASH_VERIFICATION, int enabled) 342 * 343 * > Enable strict verification of object hashsums when reading 344 * > objects from disk. This may impact performance due to an 345 * > additional checksum calculation on each object. This defaults 346 * > to enabled. 347 * 348 * @param option Option key 349 * @param ... value to set the option 350 * @return 0 on success, <0 on failure 351 */ 352 GIT_EXTERN(int) git_libgit2_opts(int option, ...); 353 354 /** @} */ 355 GIT_END_DECL 356 357 #endif 358