[libgit2.git] / include / git2 / common.h

/*
 * Copyright (C) the libgit2 contributors. All rights reserved.
 *
 * This file is part of libgit2, distributed under the GNU GPL v2 with
 * a Linking Exception. For full terms see the included COPYING file.
 */
#ifndef INCLUDE_git_common_h__
#define INCLUDE_git_common_h__

#include <time.h>
#include <stdlib.h>

#ifdef __cplusplus
# define GIT_BEGIN_DECL extern "C" {
# define GIT_END_DECL	}
#else
 /** Start declarations in C mode */
# define GIT_BEGIN_DECL /* empty */
 /** End declarations in C mode */
# define GIT_END_DECL	/* empty */
#endif

#if defined(_MSC_VER) && _MSC_VER < 1800
 GIT_BEGIN_DECL
# include "inttypes.h"
 GIT_END_DECL
/** This check is needed for importing this file in an iOS/OS X framework throws an error in Xcode otherwise.*/
#elif !defined(__CLANG_INTTYPES_H)
# include <inttypes.h>
#endif

#ifdef DOCURIUM
/*
 * This is so clang's doc parser acknowledges comments on functions
 * with size_t parameters.
 */
typedef size_t size_t;
#endif

/** Declare a public function exported for application use. */
#if __GNUC__ >= 4
# define GIT_EXTERN(type) extern \
			 __attribute__((visibility("default"))) \
			 type
#elif defined(_MSC_VER)
# define GIT_EXTERN(type) __declspec(dllexport) type
#else
# define GIT_EXTERN(type) extern type
#endif

/** Declare a function's takes printf style arguments. */
#ifdef __GNUC__
# define GIT_FORMAT_PRINTF(a,b) __attribute__((format (printf, a, b)))
#else
# define GIT_FORMAT_PRINTF(a,b) /* empty */
#endif

#if (defined(_WIN32)) && !defined(__CYGWIN__)
#define GIT_WIN32 1
#endif

#ifdef __amigaos4__
#include <netinet/in.h>
#endif

/**
 * @file git2/common.h
 * @brief Git common platform definitions
 * @defgroup git_common Git common platform definitions
 * @ingroup Git
 * @{
 */

GIT_BEGIN_DECL

/**
 * The separator used in path list strings (ie like in the PATH
 * environment variable). A semi-colon ";" is used on Windows, and
 * a colon ":" for all other systems.
 */
#ifdef GIT_WIN32
#define GIT_PATH_LIST_SEPARATOR ';'
#else
#define GIT_PATH_LIST_SEPARATOR ':'
#endif

/**
 * The maximum length of a valid git path.
 */
#define GIT_PATH_MAX 4096

/**
 * The string representation of the null object ID.
 */
#define GIT_OID_HEX_ZERO "0000000000000000000000000000000000000000"

/**
 * Return the version of the libgit2 library
 * being currently used.
 *
 * @param major Store the major version number
 * @param minor Store the minor version number
 * @param rev Store the revision (patch) number
 */
GIT_EXTERN(void) git_libgit2_version(int *major, int *minor, int *rev);

/**
 * Combinations of these values describe the features with which libgit2
 * was compiled
 */
typedef enum {
	GIT_FEATURE_THREADS	= (1 << 0),
	GIT_FEATURE_HTTPS	= (1 << 1),
	GIT_FEATURE_SSH		= (1 << 2),
	GIT_FEATURE_NSEC	= (1 << 3),
} git_feature_t;

/**
 * Query compile time options for libgit2.
 *
 * @return A combination of GIT_FEATURE_* values.
 *
 * - GIT_FEATURE_THREADS
 *   Libgit2 was compiled with thread support. Note that thread support is
 *   still to be seen as a 'work in progress' - basic object lookups are
 *   believed to be threadsafe, but other operations may not be.
 *
 * - GIT_FEATURE_HTTPS
 *   Libgit2 supports the https:// protocol. This requires the openssl
 *   library to be found when compiling libgit2.
 *
 * - GIT_FEATURE_SSH
 *   Libgit2 supports the SSH protocol for network operations. This requires
 *   the libssh2 library to be found when compiling libgit2
 */
GIT_EXTERN(int) git_libgit2_features(void);

/**
 * Global library options
 *
 * These are used to select which global option to set or get and are
 * used in `git_libgit2_opts()`.
 */
typedef enum {
	GIT_OPT_GET_MWINDOW_SIZE,
	GIT_OPT_SET_MWINDOW_SIZE,
	GIT_OPT_GET_MWINDOW_MAPPED_LIMIT,
	GIT_OPT_SET_MWINDOW_MAPPED_LIMIT,
	GIT_OPT_GET_SEARCH_PATH,
	GIT_OPT_SET_SEARCH_PATH,
	GIT_OPT_SET_CACHE_OBJECT_LIMIT,
	GIT_OPT_SET_CACHE_MAX_SIZE,
	GIT_OPT_ENABLE_CACHING,
	GIT_OPT_GET_CACHED_MEMORY,
	GIT_OPT_GET_TEMPLATE_PATH,
	GIT_OPT_SET_TEMPLATE_PATH,
	GIT_OPT_SET_SSL_CERT_LOCATIONS,
	GIT_OPT_SET_USER_AGENT,
	GIT_OPT_ENABLE_STRICT_OBJECT_CREATION,
	GIT_OPT_SET_SSL_CIPHERS,
	GIT_OPT_GET_USER_AGENT,
} git_libgit2_opt_t;

/**
 * Set or query a library global option
 *
 * Available options:
 *
 *	* opts(GIT_OPT_GET_MWINDOW_SIZE, size_t *):
 *
 *		> Get the maximum mmap window size
 *
 *	* opts(GIT_OPT_SET_MWINDOW_SIZE, size_t):
 *
 *		> Set the maximum mmap window size
 *
 *	* opts(GIT_OPT_GET_MWINDOW_MAPPED_LIMIT, size_t *):
 *
 *		> Get the maximum memory that will be mapped in total by the library
 *
 *	* opts(GIT_OPT_SET_MWINDOW_MAPPED_LIMIT, size_t):
 *
 *		>Set the maximum amount of memory that can be mapped at any time
 *		by the library
 *
 *	* opts(GIT_OPT_GET_SEARCH_PATH, int level, git_buf *buf)
 *
 *		> Get the search path for a given level of config data.  "level" must
 *		> be one of `GIT_CONFIG_LEVEL_SYSTEM`, `GIT_CONFIG_LEVEL_GLOBAL`,
 *		> `GIT_CONFIG_LEVEL_XDG`, or `GIT_CONFIG_LEVEL_PROGRAMDATA`.
 *		> The search path is written to the `out` buffer.
 *
 *	* opts(GIT_OPT_SET_SEARCH_PATH, int level, const char *path)
 *
 *		> Set the search path for a level of config data.  The search path
 *		> applied to shared attributes and ignore files, too.
 *		>
 *		> - `path` lists directories delimited by GIT_PATH_LIST_SEPARATOR.
 *		>   Pass NULL to reset to the default (generally based on environment
 *		>   variables).  Use magic path `$PATH` to include the old value
 *		>   of the path (if you want to prepend or append, for instance).
 *		>
 *		> - `level` must be `GIT_CONFIG_LEVEL_SYSTEM`,
 *		>   `GIT_CONFIG_LEVEL_GLOBAL`, `GIT_CONFIG_LEVEL_XDG`, or
 *		>   `GIT_CONFIG_LEVEL_PROGRAMDATA`.
 *
 *	* opts(GIT_OPT_SET_CACHE_OBJECT_LIMIT, git_otype type, size_t size)
 *
 *		> Set the maximum data size for the given type of object to be
 *		> considered eligible for caching in memory.  Setting to value to
 *		> zero means that that type of object will not be cached.
 *		> Defaults to 0 for GIT_OBJ_BLOB (i.e. won't cache blobs) and 4k
 *		> for GIT_OBJ_COMMIT, GIT_OBJ_TREE, and GIT_OBJ_TAG.
 *
 *	* opts(GIT_OPT_SET_CACHE_MAX_SIZE, ssize_t max_storage_bytes)
 *
 *		> Set the maximum total data size that will be cached in memory
 *		> across all repositories before libgit2 starts evicting objects
 *		> from the cache.  This is a soft limit, in that the library might
 *		> briefly exceed it, but will start aggressively evicting objects
 *		> from cache when that happens.  The default cache size is 256MB.
 *
 *	* opts(GIT_OPT_ENABLE_CACHING, int enabled)
 *
 *		> Enable or disable caching completely.
 *		>
 *		> Because caches are repository-specific, disabling the cache
 *		> cannot immediately clear all cached objects, but each cache will
 *		> be cleared on the next attempt to update anything in it.
 *
 *	* opts(GIT_OPT_GET_CACHED_MEMORY, ssize_t *current, ssize_t *allowed)
 *
 *		> Get the current bytes in cache and the maximum that would be
 *		> allowed in the cache.
 *
 *	* opts(GIT_OPT_GET_TEMPLATE_PATH, git_buf *out)
 *
 *		> Get the default template path.
 *		> The path is written to the `out` buffer.
 *
 *	* opts(GIT_OPT_SET_TEMPLATE_PATH, const char *path)
 *
 *		> Set the default template path.
 *		>
 *		> - `path` directory of template.
 *
 *	* opts(GIT_OPT_SET_SSL_CERT_LOCATIONS, const char *file, const char *path)
 *
 *		> Set the SSL certificate-authority locations.
 *		>
 *		> - `file` is the location of a file containing several
 *		>   certificates concatenated together.
 *		> - `path` is the location of a directory holding several
 *		>   certificates, one per file.
 *		>
 * 		> Either parameter may be `NULL`, but not both.
 *
 *	* opts(GIT_OPT_SET_USER_AGENT, const char *user_agent)
 *
 *		> Set the value of the User-Agent header.  This value will be
 *		> appended to "git/1.0", for compatibility with other git clients.
 *		>
 *		> - `user_agent` is the value that will be delivered as the
 *		>   User-Agent header on HTTP requests.
 *
 *	* opts(GIT_OPT_ENABLE_STRICT_OBJECT_CREATION, int enabled)
 *
 *		> Enable strict input validation when creating new objects
 *		> to ensure that all inputs to the new objects are valid.  For
 *		> example, when this is enabled, the parent(s) and tree inputs
 *		> will be validated when creating a new commit.  This defaults
 *		> to enabled.
 *
 *	* opts(GIT_OPT_SET_SSL_CIPHERS, const char *ciphers)
 *
 *		> Set the SSL ciphers use for HTTPS connections.
 *		>
 *		> - `ciphers` is the list of ciphers that are eanbled.
 *
 * @param option Option key
 * @param ... value to set the option
 * @return 0 on success, <0 on failure
 */
GIT_EXTERN(int) git_libgit2_opts(int option, ...);

/** @} */
GIT_END_DECL

#endif
Commit	Line	Data
f5918330	1	/*
359fc2d2	2	* Copyright (C) the libgit2 contributors. All rights reserved.
f5918330	3	*
bb742ede VM	4	* This file is part of libgit2, distributed under the GNU GPL v2 with
bb742ede VM	5	* a Linking Exception. For full terms see the included COPYING file.
f5918330	6	*/
c15648cb SP	7	#ifndef INCLUDE_git_common_h__
	8	#define INCLUDE_git_common_h__
	9
58519018	10	#include <time.h>
00571828	11	#include <stdlib.h>
e3fe32b6	12
c15648cb	13	#ifdef __cplusplus
87d9869f VM	14	# define GIT_BEGIN_DECL extern "C" {
87d9869f VM	15	# define GIT_END_DECL }
c15648cb	16	#else
87d9869f VM	17	/** Start declarations in C mode */
	18	# define GIT_BEGIN_DECL /* empty */
	19	/** End declarations in C mode */
	20	# define GIT_END_DECL /* empty */
c15648cb SP	21	#endif
c15648cb SP	22
240a85cf	23	#if defined(_MSC_VER) && _MSC_VER < 1800
0f9b6742 ET	24	GIT_BEGIN_DECL
	25	# include "inttypes.h"
	26	GIT_END_DECL
0ac4a5de PB	27	/** This check is needed for importing this file in an iOS/OS X framework throws an error in Xcode otherwise.*/
0ac4a5de PB	28	#elif !defined(__CLANG_INTTYPES_H)
0f9b6742 ET	29	# include <inttypes.h>
	30	#endif
	31
98444536 CMN	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
16a67770	40	/** Declare a public function exported for application use. */
d2a1861e	41	#if __GNUC__ >= 4
3b8ab0b9	42	# define GIT_EXTERN(type) extern \
87d9869f VM	43	__attribute__((visibility("default"))) \
87d9869f VM	44	type
25e9b4dd	45	#elif defined(_MSC_VER)
79fdde49	46	# define GIT_EXTERN(type) __declspec(dllexport) type
16a67770	47	#else
3b8ab0b9	48	# define GIT_EXTERN(type) extern type
16a67770 SP	49	#endif
16a67770 SP	50
15bffce9 SP	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
c02f1392	58	#if (defined(_WIN32)) && !defined(__CYGWIN__)
0657e46d RG	59	#define GIT_WIN32 1
	60	#endif
	61
0f5e1f3b	62	#ifdef __amigaos4__
327fb51c	63	#include <netinet/in.h>
0f5e1f3b CY	64	#endif
0f5e1f3b CY	65
c15648cb	66	/**
f5918330	67	* @file git2/common.h
c15648cb SP	68	* @brief Git common platform definitions
	69	* @defgroup git_common Git common platform definitions
	70	* @ingroup Git
	71	* @{
	72	*/
c15648cb	73
16a67770	74	GIT_BEGIN_DECL
00571828	75
0657e46d RG	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	/**
b1ec25fa	88	* The maximum length of a valid git path.
0657e46d RG	89	*/
	90	#define GIT_PATH_MAX 4096
	91
613d5eb9 PK	92	/**
	93	* The string representation of the null object ID.
	94	*/
	95	#define GIT_OID_HEX_ZERO "0000000000000000000000000000000000000000"
	96
536955f9 VM	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
e564e496	107	/**
c9f5298b VM	108	* Combinations of these values describe the features with which libgit2
c9f5298b VM	109	* was compiled
e564e496	110	*/
0f1f9833	111	typedef enum {
ebb3c506	112	GIT_FEATURE_THREADS = (1 << 0),
0269833f AR	113	GIT_FEATURE_HTTPS = (1 << 1),
	114	GIT_FEATURE_SSH = (1 << 2),
	115	GIT_FEATURE_NSEC = (1 << 3),
2491c416	116	} git_feature_t;
e564e496 SC	117
	118	/**
	119	* Query compile time options for libgit2.
	120	*
ebb3c506	121	* @return A combination of GIT_FEATURE_* values.
e564e496	122	*
ebb3c506	123	* - GIT_FEATURE_THREADS
0f1f9833 RB	124	* Libgit2 was compiled with thread support. Note that thread support is
	125	* still to be seen as a 'work in progress' - basic object lookups are
	126	* believed to be threadsafe, but other operations may not be.
e564e496	127	*
ebb3c506	128	* - GIT_FEATURE_HTTPS
0f1f9833 RB	129	* Libgit2 supports the https:// protocol. This requires the openssl
0f1f9833 RB	130	* library to be found when compiling libgit2.
c9f5298b	131	*
ebb3c506	132	* - GIT_FEATURE_SSH
c9f5298b	133	* Libgit2 supports the SSH protocol for network operations. This requires
96484ecd	134	* the libssh2 library to be found when compiling libgit2
e564e496	135	*/
c9f5298b	136	GIT_EXTERN(int) git_libgit2_features(void);
e564e496	137
a295bd2d CMN	138	/**
	139	* Global library options
	140	*
	141	* These are used to select which global option to set or get and are
	142	* used in `git_libgit2_opts()`.
	143	*/
2e62e7c2	144	typedef enum {
a0f777c8 VM	145	GIT_OPT_GET_MWINDOW_SIZE,
	146	GIT_OPT_SET_MWINDOW_SIZE,
	147	GIT_OPT_GET_MWINDOW_MAPPED_LIMIT,
5540d947 RB	148	GIT_OPT_SET_MWINDOW_MAPPED_LIMIT,
	149	GIT_OPT_GET_SEARCH_PATH,
	150	GIT_OPT_SET_SEARCH_PATH,
d8771592 VM	151	GIT_OPT_SET_CACHE_OBJECT_LIMIT,
d8771592 VM	152	GIT_OPT_SET_CACHE_MAX_SIZE,
a2378ae4	153	GIT_OPT_ENABLE_CACHING,
b99b10f2 L	154	GIT_OPT_GET_CACHED_MEMORY,
b99b10f2 L	155	GIT_OPT_GET_TEMPLATE_PATH,
737b445a WS	156	GIT_OPT_SET_TEMPLATE_PATH,
737b445a WS	157	GIT_OPT_SET_SSL_CERT_LOCATIONS,
de870533	158	GIT_OPT_SET_USER_AGENT,
22a19f5b	159	GIT_OPT_ENABLE_STRICT_OBJECT_CREATION,
fa72d6da	160	GIT_OPT_SET_SSL_CIPHERS,
f1dba144	161	GIT_OPT_GET_USER_AGENT,
2e62e7c2	162	} git_libgit2_opt_t;
59853eff VM	163
	164	/**
	165	* Set or query a library global option
	166	*
	167	* Available options:
	168	*
b4117e19	169	* * opts(GIT_OPT_GET_MWINDOW_SIZE, size_t *):
59853eff	170	*
b4117e19	171	* > Get the maximum mmap window size
5540d947	172	*
b4117e19	173	* * opts(GIT_OPT_SET_MWINDOW_SIZE, size_t):
5540d947	174	*
b4117e19 CMN	175	* > Set the maximum mmap window size
	176	*
	177	* * opts(GIT_OPT_GET_MWINDOW_MAPPED_LIMIT, size_t *):
	178	*
	179	* > Get the maximum memory that will be mapped in total by the library
	180	*
	181	* * opts(GIT_OPT_SET_MWINDOW_MAPPED_LIMIT, size_t):
	182	*
	183	* >Set the maximum amount of memory that can be mapped at any time
59853eff VM	184	* by the library
59853eff VM	185	*
42dee8ec	186	* * opts(GIT_OPT_GET_SEARCH_PATH, int level, git_buf *buf)
b4117e19 CMN	187	*
b4117e19 CMN	188	* > Get the search path for a given level of config data. "level" must
3eac1037 ET	189	* > be one of `GIT_CONFIG_LEVEL_SYSTEM`, `GIT_CONFIG_LEVEL_GLOBAL`,
	190	* > `GIT_CONFIG_LEVEL_XDG`, or `GIT_CONFIG_LEVEL_PROGRAMDATA`.
	191	* > The search path is written to the `out` buffer.
b4117e19 CMN	192	*
	193	* * opts(GIT_OPT_SET_SEARCH_PATH, int level, const char *path)
	194	*
	195	* > Set the search path for a level of config data. The search path
	196	* > applied to shared attributes and ignore files, too.
	197	* >
	198	* > - `path` lists directories delimited by GIT_PATH_LIST_SEPARATOR.
	199	* > Pass NULL to reset to the default (generally based on environment
	200	* > variables). Use magic path `$PATH` to include the old value
	201	* > of the path (if you want to prepend or append, for instance).
	202	* >
3eac1037 ET	203	* > - `level` must be `GIT_CONFIG_LEVEL_SYSTEM`,
	204	* > `GIT_CONFIG_LEVEL_GLOBAL`, `GIT_CONFIG_LEVEL_XDG`, or
	205	* > `GIT_CONFIG_LEVEL_PROGRAMDATA`.
5540d947	206	*
2e62e7c2 RB	207	* * opts(GIT_OPT_SET_CACHE_OBJECT_LIMIT, git_otype type, size_t size)
	208	*
	209	* > Set the maximum data size for the given type of object to be
	210	* > considered eligible for caching in memory. Setting to value to
	211	* > zero means that that type of object will not be cached.
	212	* > Defaults to 0 for GIT_OBJ_BLOB (i.e. won't cache blobs) and 4k
	213	* > for GIT_OBJ_COMMIT, GIT_OBJ_TREE, and GIT_OBJ_TAG.
	214	*
	215	* * opts(GIT_OPT_SET_CACHE_MAX_SIZE, ssize_t max_storage_bytes)
	216	*
	217	* > Set the maximum total data size that will be cached in memory
	218	* > across all repositories before libgit2 starts evicting objects
	219	* > from the cache. This is a soft limit, in that the library might
	220	* > briefly exceed it, but will start aggressively evicting objects
6057c4a0	221	* > from cache when that happens. The default cache size is 256MB.
2e62e7c2 RB	222	*
	223	* * opts(GIT_OPT_ENABLE_CACHING, int enabled)
	224	*
	225	* > Enable or disable caching completely.
	226	* >
	227	* > Because caches are repository-specific, disabling the cache
	228	* > cannot immediately clear all cached objects, but each cache will
	229	* > be cleared on the next attempt to update anything in it.
	230	*
	231	* * opts(GIT_OPT_GET_CACHED_MEMORY, ssize_t current, ssize_t allowed)
	232	*
	233	* > Get the current bytes in cache and the maximum that would be
	234	* > allowed in the cache.
	235	*
42dee8ec	236	* * opts(GIT_OPT_GET_TEMPLATE_PATH, git_buf *out)
b99b10f2 L	237	*
b99b10f2 L	238	* > Get the default template path.
42dee8ec	239	* > The path is written to the `out` buffer.
b99b10f2 L	240	*
	241	* * opts(GIT_OPT_SET_TEMPLATE_PATH, const char *path)
	242	*
	243	* > Set the default template path.
	244	* >
	245	* > - `path` directory of template.
	246	*
737b445a WS	247	* * opts(GIT_OPT_SET_SSL_CERT_LOCATIONS, const char file, const char path)
	248	*
	249	* > Set the SSL certificate-authority locations.
	250	* >
	251	* > - `file` is the location of a file containing several
	252	* > certificates concatenated together.
	253	* > - `path` is the location of a directory holding several
	254	* > certificates, one per file.
	255	* >
	256	* > Either parameter may be `NULL`, but not both.
	257	*
de870533 CMN	258	* * opts(GIT_OPT_SET_USER_AGENT, const char *user_agent)
de870533 CMN	259	*
5bc93eae ET	260	* > Set the value of the User-Agent header. This value will be
	261	* > appended to "git/1.0", for compatibility with other git clients.
	262	* >
	263	* > - `user_agent` is the value that will be delivered as the
	264	* > User-Agent header on HTTP requests.
	265	*
22a19f5b ET	266	* * opts(GIT_OPT_ENABLE_STRICT_OBJECT_CREATION, int enabled)
	267	*
	268	* > Enable strict input validation when creating new objects
	269	* > to ensure that all inputs to the new objects are valid. For
	270	* > example, when this is enabled, the parent(s) and tree inputs
	271	* > will be validated when creating a new commit. This defaults
93392cdd ET	272	* > to enabled.
93392cdd ET	273	*
fa72d6da DB	274	* * opts(GIT_OPT_SET_SSL_CIPHERS, const char *ciphers)
	275	*
	276	* > Set the SSL ciphers use for HTTPS connections.
	277	* >
	278	* > - `ciphers` is the list of ciphers that are eanbled.
22a19f5b	279	*
5540d947 RB	280	* @param option Option key
	281	* @param ... value to set the option
	282	* @return 0 on success, <0 on failure
59853eff	283	*/
5540d947	284	GIT_EXTERN(int) git_libgit2_opts(int option, ...);
59853eff	285
c15648cb SP	286	/** @} */
c15648cb SP	287	GIT_END_DECL
b46708aa	288
c15648cb	289	#endif